unity-mcp-cli 0.66.0 → 0.67.0

package/dist/lib/progress.js

@@ -0,0 +1,16 @@
+/**
+ * Forward a single progress event to the caller's optional callback,
+ * swallowing any exception the callback throws. A broken onProgress
+ * handler must never abort the underlying library operation.
+ */
+export function emitProgress(onProgress, event) {
+    if (!onProgress)
+        return;
+    try {
+        onProgress(event);
+    }
+    catch {
+        // Intentionally ignored — see doc comment.
+    }
+}
+//# sourceMappingURL=progress.js.map

package/dist/lib/progress.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"progress.js","sourceRoot":"","sources":["../../src/lib/progress.ts"],"names":[],"mappings":"AAEA;;;;GAIG;AACH,MAAM,UAAU,YAAY,CAAC,UAAwC,EAAE,KAAoB;IACzF,IAAI,CAAC,UAAU;QAAE,OAAO;IACxB,IAAI,CAAC;QACH,UAAU,CAAC,KAAK,CAAC,CAAC;IACpB,CAAC;IAAC,MAAM,CAAC;QACP,2CAA2C;IAC7C,CAAC;AACH,CAAC"}

package/dist/lib/remove-plugin.d.ts

@@ -0,0 +1,7 @@
+import type { RemovePluginOptions, RemoveResult } from './types.js';
+/**
+ * Remove the Unity-MCP plugin from a Unity project. Library-safe:
+ * never calls `process.exit`, never prints to stdout / stderr, never
+ * throws past the public boundary.
+ */
+export declare function removePlugin(opts: RemovePluginOptions): Promise<RemoveResult>;

package/dist/lib/remove-plugin.js

@@ -0,0 +1,51 @@
+import { removePluginFromManifest } from '../utils/manifest.js';
+import { silentLogger } from './logger.js';
+import { emitProgress } from './progress.js';
+import { requireUnityProject } from './validation.js';
+/**
+ * Remove the Unity-MCP plugin from a Unity project. Library-safe:
+ * never calls `process.exit`, never prints to stdout / stderr, never
+ * throws past the public boundary.
+ */
+export async function removePlugin(opts) {
+    const warnings = [];
+    try {
+        const validated = requireUnityProject(opts?.unityProjectPath);
+        if (!validated.ok) {
+            return {
+                success: false,
+                manifestPath: validated.manifestPath,
+                warnings,
+                error: validated.error,
+            };
+        }
+        const { projectPath } = validated;
+        emitProgress(opts.onProgress, { phase: 'start', message: `Removing Unity-MCP plugin from ${projectPath}` });
+        const result = removePluginFromManifest(projectPath, silentLogger);
+        if (!result.removed) {
+            warnings.push('Unity-MCP plugin was not installed. Nothing was removed.');
+        }
+        emitProgress(opts.onProgress, {
+            phase: 'manifest-patched',
+            message: result.removed
+                ? `Removed plugin from ${result.manifestPath}`
+                : 'manifest.json left untouched (plugin not installed).',
+            manifestPath: result.manifestPath,
+        });
+        emitProgress(opts.onProgress, { phase: 'done', message: 'Remove complete.' });
+        return {
+            success: true,
+            removed: result.removed,
+            manifestPath: result.manifestPath,
+            warnings,
+        };
+    }
+    catch (err) {
+        return {
+            success: false,
+            warnings,
+            error: err instanceof Error ? err : new Error(String(err)),
+        };
+    }
+}
+//# sourceMappingURL=remove-plugin.js.map

package/dist/lib/remove-plugin.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"remove-plugin.js","sourceRoot":"","sources":["../../src/lib/remove-plugin.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,wBAAwB,EAAE,MAAM,sBAAsB,CAAC;AAChE,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAC3C,OAAO,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAC7C,OAAO,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAC;AAGtD;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY,CAAC,IAAyB;IAC1D,MAAM,QAAQ,GAAa,EAAE,CAAC;IAE9B,IAAI,CAAC;QACH,MAAM,SAAS,GAAG,mBAAmB,CAAC,IAAI,EAAE,gBAAgB,CAAC,CAAC;QAC9D,IAAI,CAAC,SAAS,CAAC,EAAE,EAAE,CAAC;YAClB,OAAO;gBACL,OAAO,EAAE,KAAK;gBACd,YAAY,EAAE,SAAS,CAAC,YAAY;gBACpC,QAAQ;gBACR,KAAK,EAAE,SAAS,CAAC,KAAK;aACvB,CAAC;QACJ,CAAC;QACD,MAAM,EAAE,WAAW,EAAE,GAAG,SAAS,CAAC;QAElC,YAAY,CAAC,IAAI,CAAC,UAAU,EAAE,EAAE,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,kCAAkC,WAAW,EAAE,EAAE,CAAC,CAAC;QAE5G,MAAM,MAAM,GAAG,wBAAwB,CAAC,WAAW,EAAE,YAAY,CAAC,CAAC;QAEnE,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;YACpB,QAAQ,CAAC,IAAI,CAAC,0DAA0D,CAAC,CAAC;QAC5E,CAAC;QAED,YAAY,CAAC,IAAI,CAAC,UAAU,EAAE;YAC5B,KAAK,EAAE,kBAAkB;YACzB,OAAO,EAAE,MAAM,CAAC,OAAO;gBACrB,CAAC,CAAC,uBAAuB,MAAM,CAAC,YAAY,EAAE;gBAC9C,CAAC,CAAC,sDAAsD;YAC1D,YAAY,EAAE,MAAM,CAAC,YAAY;SAClC,CAAC,CAAC;QAEH,YAAY,CAAC,IAAI,CAAC,UAAU,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,kBAAkB,EAAE,CAAC,CAAC;QAE9E,OAAO;YACL,OAAO,EAAE,IAAI;YACb,OAAO,EAAE,MAAM,CAAC,OAAO;YACvB,YAAY,EAAE,MAAM,CAAC,YAAY;YACjC,QAAQ;SACT,CAAC;IACJ,CAAC;IAAC,OAAO,GAAY,EAAE,CAAC;QACtB,OAAO;YACL,OAAO,EAAE,KAAK;YACd,QAAQ;YACR,KAAK,EAAE,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;SAC3D,CAAC;IACJ,CAAC;AACH,CAAC"}

package/dist/lib/setup-mcp.d.ts

@@ -0,0 +1,12 @@
+import type { SetupMcpOptions, SetupMcpResult } from './types.js';
+/**
+ * Write MCP configuration for the given AI agent, so it can talk to
+ * Unity-MCP. Library-safe: no stdout noise, no process.exit, no throws
+ * past the public boundary.
+ */
+export declare function setupMcp(opts: SetupMcpOptions): Promise<SetupMcpResult>;
+/**
+ * List every agent id known to the `setupMcp` function. Useful for
+ * consumer UIs that want to render a picker.
+ */
+export declare function listAgentIds(): string[];

package/dist/lib/setup-mcp.js

@@ -0,0 +1,141 @@
+import * as fs from 'fs';
+import * as path from 'path';
+import { generatePortFromDirectory } from '../utils/port.js';
+import { readConfig, resolveConnectionFromConfig } from '../utils/config.js';
+import { getAgentById, getAgentIds, resolveServerBinaryPath, writeJsonAgentConfig, writeTomlAgentConfig, MCP_SERVER_NAME, } from '../utils/agents.js';
+import { emitProgress } from './progress.js';
+import { requireExistingPath } from './validation.js';
+function isValidTransport(t) {
+    return t === 'stdio' || t === 'http';
+}
+/**
+ * Extract a port from a `host` URL string, falling back to the
+ * project-directory-derived deterministic port on any parse failure.
+ */
+function portFromHost(host, projectPath) {
+    if (!host)
+        return generatePortFromDirectory(projectPath);
+    try {
+        return parseInt(new URL(host).port, 10) || generatePortFromDirectory(projectPath);
+    }
+    catch {
+        return generatePortFromDirectory(projectPath);
+    }
+}
+/**
+ * Write MCP configuration for the given AI agent, so it can talk to
+ * Unity-MCP. Library-safe: no stdout noise, no process.exit, no throws
+ * past the public boundary.
+ */
+export async function setupMcp(opts) {
+    const warnings = [];
+    const nextSteps = [];
+    try {
+        if (!opts || typeof opts.agentId !== 'string' || opts.agentId.length === 0) {
+            return {
+                success: false,
+                warnings,
+                nextSteps,
+                error: new Error(`agentId is required. Available agent IDs: ${getAgentIds().join(', ')}`),
+            };
+        }
+        const agent = getAgentById(opts.agentId);
+        if (!agent) {
+            return {
+                success: false,
+                warnings,
+                nextSteps,
+                error: new Error(`Unknown agent: "${opts.agentId}". Available agent IDs: ${getAgentIds().join(', ')}`),
+            };
+        }
+        const transport = opts.transport ?? 'http';
+        if (!isValidTransport(transport)) {
+            return {
+                success: false,
+                warnings,
+                nextSteps,
+                error: new Error(`Invalid transport: "${transport}". Must be "stdio" or "http".`),
+            };
+        }
+        // Resolve project path. If the caller supplied one explicitly it
+        // must exist; otherwise fall back to cwd (matches CLI behaviour).
+        let projectPath;
+        if (opts.unityProjectPath) {
+            const validated = requireExistingPath(opts.unityProjectPath);
+            if (!validated.ok) {
+                return { success: false, warnings, nextSteps, error: validated.error };
+            }
+            projectPath = validated.projectPath;
+        }
+        else {
+            projectPath = path.resolve(process.cwd());
+        }
+        emitProgress(opts.onProgress, {
+            phase: 'start',
+            message: `Configuring ${agent.name} (${transport}) for ${projectPath}`,
+        });
+        const config = readConfig(projectPath);
+        const fromConfig = config
+            ? resolveConnectionFromConfig(config)
+            : { url: undefined, token: undefined };
+        const port = portFromHost(config?.host, projectPath);
+        const timeout = config?.timeoutMs ?? 10000;
+        const auth = config?.authOption ?? 'none';
+        const token = opts.token ?? fromConfig.token ?? '';
+        const authRequired = auth === 'required';
+        const serverPath = resolveServerBinaryPath(projectPath).replace(/\\/g, '/');
+        // Resolve URL for HTTP — explicit override, then config, then
+        // deterministic localhost fallback. Trailing slash stripped.
+        const serverUrl = (opts.url ?? fromConfig.url ?? `http://localhost:${port}`).replace(/\/$/, '');
+        const configPath = agent.getConfigPath(projectPath);
+        let props;
+        let removeKeys;
+        if (transport === 'stdio') {
+            props = agent.getStdioProps(serverPath, port, timeout, auth, token);
+            removeKeys = agent.stdioRemoveKeys;
+        }
+        else {
+            props = agent.getHttpProps(serverUrl, token, authRequired);
+            removeKeys = agent.httpRemoveKeys;
+        }
+        if (agent.configFormat === 'toml') {
+            writeTomlAgentConfig(configPath, agent.bodyPath, MCP_SERVER_NAME, props, removeKeys);
+        }
+        else {
+            writeJsonAgentConfig(configPath, agent.bodyPath, MCP_SERVER_NAME, props, removeKeys);
+        }
+        emitProgress(opts.onProgress, {
+            phase: 'manifest-patched',
+            message: `Wrote ${configPath}`,
+            manifestPath: configPath,
+        });
+        if (transport === 'stdio' && !fs.existsSync(serverPath.replace(/\//g, path.sep))) {
+            warnings.push('Server binary not found. Open Unity with the MCP plugin to download it automatically.');
+        }
+        emitProgress(opts.onProgress, { phase: 'done', message: `${agent.name} configured successfully.` });
+        return {
+            success: true,
+            agentId: agent.id,
+            configPath,
+            transport,
+            warnings,
+            nextSteps,
+        };
+    }
+    catch (err) {
+        return {
+            success: false,
+            warnings,
+            nextSteps,
+            error: err instanceof Error ? err : new Error(String(err)),
+        };
+    }
+}
+/**
+ * List every agent id known to the `setupMcp` function. Useful for
+ * consumer UIs that want to render a picker.
+ */
+export function listAgentIds() {
+    return getAgentIds();
+}
+//# sourceMappingURL=setup-mcp.js.map

package/dist/lib/setup-mcp.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"setup-mcp.js","sourceRoot":"","sources":["../../src/lib/setup-mcp.ts"],"names":[],"mappings":"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"}

package/dist/lib/types.d.ts

@@ -0,0 +1,132 @@
+/**
+ * Discriminated union describing every progress event the library can
+ * emit to the optional `onProgress` callback.
+ *
+ * Consumers can narrow on `event.phase` to decide what to render.
+ */
+export type ProgressEvent = {
+    phase: 'start';
+    message: string;
+} | {
+    phase: 'manifest-patched';
+    message: string;
+    manifestPath: string;
+} | {
+    phase: 'dependencies-resolved';
+    message: string;
+    version: string;
+} | {
+    phase: 'done';
+    message: string;
+};
+export type ProgressCallback = (event: ProgressEvent) => void;
+export interface InstallPluginOptions {
+    /** Absolute or relative path to the Unity project's root. */
+    unityProjectPath: string;
+    /**
+     * Plugin version to install. When omitted, the latest version is
+     * resolved from OpenUPM.
+     */
+    version?: string;
+    /**
+     * Optional progress callback — fires for `start`,
+     * `dependencies-resolved` (when the version was auto-resolved),
+     * `manifest-patched`, and `done`.
+     */
+    onProgress?: ProgressCallback;
+}
+export interface InstallResult {
+    /** `true` when the manifest was updated (or already correct); `false` on error. */
+    success: boolean;
+    /** Final plugin version in the manifest. Populated on success. */
+    installedVersion?: string;
+    /** Absolute path to the manifest.json that was inspected / written. */
+    manifestPath?: string;
+    /** Non-fatal warnings collected during the run (e.g. skipped downgrade). */
+    warnings: string[];
+    /** Suggested next steps for the caller to surface to a human user. */
+    nextSteps: string[];
+    /** Populated when `success === false`. Never thrown past this boundary. */
+    error?: Error;
+}
+export interface RemovePluginOptions {
+    unityProjectPath: string;
+    onProgress?: ProgressCallback;
+}
+export interface RemoveResult {
+    success: boolean;
+    /** `true` when the plugin dependency was present and has been removed. */
+    removed?: boolean;
+    manifestPath?: string;
+    warnings: string[];
+    error?: Error;
+}
+/** Action applied to a set of MCP features (tools, prompts, or resources). */
+export interface FeatureAction {
+    /** Explicit names to enable. */
+    enableNames?: string[];
+    /** Explicit names to disable. */
+    disableNames?: string[];
+    /** Enable every feature already present in the config. */
+    enableAll?: boolean;
+    /** Disable every feature already present in the config. */
+    disableAll?: boolean;
+}
+export interface ConfigureOptions {
+    unityProjectPath: string;
+    /** Whether to apply changes to tools. Omit to leave tools untouched. */
+    tools?: FeatureAction;
+    prompts?: FeatureAction;
+    resources?: FeatureAction;
+    onProgress?: ProgressCallback;
+}
+export interface McpFeatureSnapshot {
+    name: string;
+    enabled: boolean;
+}
+export interface ConfigureResult {
+    success: boolean;
+    /** Absolute path to the `AI-Game-Developer-Config.json` that was written. */
+    configPath?: string;
+    /** A read-only snapshot of the post-write config. */
+    snapshot?: {
+        host?: string;
+        keepConnected?: boolean;
+        transportMethod?: string;
+        authOption?: string;
+        tools: McpFeatureSnapshot[];
+        prompts: McpFeatureSnapshot[];
+        resources: McpFeatureSnapshot[];
+    };
+    warnings: string[];
+    error?: Error;
+}
+export type McpTransport = 'stdio' | 'http';
+export interface SetupMcpOptions {
+    /**
+     * Agent to configure. Use `listAgentIds()` to discover valid values
+     * (e.g. `'claude-code'`, `'cursor'`, `'codex'`, …).
+     */
+    agentId: string;
+    /** Optional Unity project path. Defaults to `process.cwd()` if omitted. */
+    unityProjectPath?: string;
+    /** Transport to write — defaults to `'http'`. */
+    transport?: McpTransport;
+    /** Explicit server URL override (for http transport). */
+    url?: string;
+    /** Auth token override. */
+    token?: string;
+    onProgress?: ProgressCallback;
+}
+export interface SetupMcpResult {
+    success: boolean;
+    /** The agent whose config file was written (undefined on error). */
+    agentId?: string;
+    /** Absolute path to the agent config file that was written. */
+    configPath?: string;
+    /** Transport actually written. */
+    transport?: McpTransport;
+    warnings: string[];
+    nextSteps: string[];
+    error?: Error;
+}

package/dist/lib/types.js

@@ -0,0 +1,8 @@
+// Shared public types for the unity-mcp-cli library API.
+//
+// This file is re-exported from `lib.ts` — consumers should import
+// from `unity-mcp-cli` (the package root), NOT from deep paths.
+//
+// No top-level side effects, no runtime deps beyond TypeScript types.
+export {};
+//# sourceMappingURL=types.js.map

package/dist/lib/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/lib/types.ts"],"names":[],"mappings":"AAAA,yDAAyD;AACzD,EAAE;AACF,mEAAmE;AACnE,gEAAgE;AAChE,EAAE;AACF,sEAAsE"}

package/dist/lib/validation.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Small, side-effect-free input-validation helpers shared by the
+ * library-facing API functions. Each helper returns a discriminated
+ * union so call sites can pattern-match without throwing across the
+ * public boundary.
+ */
+export type ValidatedPath = {
+    ok: true;
+    projectPath: string;
+} | {
+    ok: false;
+    error: Error;
+};
+export type ValidatedUnityProject = {
+    ok: true;
+    projectPath: string;
+    manifestPath: string;
+} | {
+    ok: false;
+    manifestPath?: string;
+    error: Error;
+};
+/**
+ * Require a non-empty string and resolve it to an absolute path.
+ */
+export declare function requireProjectPath(raw: unknown): ValidatedPath;
+/**
+ * Require a non-empty path AND that the path hosts a Unity project
+ * (identified by the presence of `Packages/manifest.json`).
+ */
+export declare function requireUnityProject(raw: unknown): ValidatedUnityProject;
+/**
+ * Require that the given path exists on disk (does not need to host a
+ * Unity manifest). Used by `configure()` which only needs a directory
+ * to drop a config file into.
+ */
+export declare function requireExistingPath(raw: unknown): ValidatedPath;

package/dist/lib/validation.js

@@ -0,0 +1,50 @@
+import * as fs from 'fs';
+import * as path from 'path';
+/**
+ * Require a non-empty string and resolve it to an absolute path.
+ */
+export function requireProjectPath(raw) {
+    if (typeof raw !== 'string' || raw.length === 0) {
+        return {
+            ok: false,
+            error: new Error('unityProjectPath is required and must be a non-empty string.'),
+        };
+    }
+    return { ok: true, projectPath: path.resolve(raw) };
+}
+/**
+ * Require a non-empty path AND that the path hosts a Unity project
+ * (identified by the presence of `Packages/manifest.json`).
+ */
+export function requireUnityProject(raw) {
+    const outer = requireProjectPath(raw);
+    if (!outer.ok)
+        return outer;
+    const manifestPath = path.join(outer.projectPath, 'Packages', 'manifest.json');
+    if (!fs.existsSync(manifestPath)) {
+        return {
+            ok: false,
+            manifestPath,
+            error: new Error(`Not a valid Unity project (missing Packages/manifest.json): ${outer.projectPath}`),
+        };
+    }
+    return { ok: true, projectPath: outer.projectPath, manifestPath };
+}
+/**
+ * Require that the given path exists on disk (does not need to host a
+ * Unity manifest). Used by `configure()` which only needs a directory
+ * to drop a config file into.
+ */
+export function requireExistingPath(raw) {
+    const outer = requireProjectPath(raw);
+    if (!outer.ok)
+        return outer;
+    if (!fs.existsSync(outer.projectPath)) {
+        return {
+            ok: false,
+            error: new Error(`Project path does not exist: ${outer.projectPath}`),
+        };
+    }
+    return outer;
+}
+//# sourceMappingURL=validation.js.map

package/dist/lib/validation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validation.js","sourceRoot":"","sources":["../../src/lib/validation.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,IAAI,CAAC;AACzB,OAAO,KAAK,IAAI,MAAM,MAAM,CAAC;AAiB7B;;GAEG;AACH,MAAM,UAAU,kBAAkB,CAAC,GAAY;IAC7C,IAAI,OAAO,GAAG,KAAK,QAAQ,IAAI,GAAG,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAChD,OAAO;YACL,EAAE,EAAE,KAAK;YACT,KAAK,EAAE,IAAI,KAAK,CAAC,8DAA8D,CAAC;SACjF,CAAC;IACJ,CAAC;IACD,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,WAAW,EAAE,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC;AACtD,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,mBAAmB,CAAC,GAAY;IAC9C,MAAM,KAAK,GAAG,kBAAkB,CAAC,GAAG,CAAC,CAAC;IACtC,IAAI,CAAC,KAAK,CAAC,EAAE;QAAE,OAAO,KAAK,CAAC;IAC5B,MAAM,YAAY,GAAG,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,WAAW,EAAE,UAAU,EAAE,eAAe,CAAC,CAAC;IAC/E,IAAI,CAAC,EAAE,CAAC,UAAU,CAAC,YAAY,CAAC,EAAE,CAAC;QACjC,OAAO;YACL,EAAE,EAAE,KAAK;YACT,YAAY;YACZ,KAAK,EAAE,IAAI,KAAK,CACd,+DAA+D,KAAK,CAAC,WAAW,EAAE,CACnF;SACF,CAAC;IACJ,CAAC;IACD,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,WAAW,EAAE,KAAK,CAAC,WAAW,EAAE,YAAY,EAAE,CAAC;AACpE,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,mBAAmB,CAAC,GAAY;IAC9C,MAAM,KAAK,GAAG,kBAAkB,CAAC,GAAG,CAAC,CAAC;IACtC,IAAI,CAAC,KAAK,CAAC,EAAE;QAAE,OAAO,KAAK,CAAC;IAC5B,IAAI,CAAC,EAAE,CAAC,UAAU,CAAC,KAAK,CAAC,WAAW,CAAC,EAAE,CAAC;QACtC,OAAO;YACL,EAAE,EAAE,KAAK;YACT,KAAK,EAAE,IAAI,KAAK,CAAC,gCAAgC,KAAK,CAAC,WAAW,EAAE,CAAC;SACtE,CAAC;IACJ,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC"}

package/dist/lib.d.ts

@@ -0,0 +1,5 @@
+export { installPlugin } from './lib/install-plugin.js';
+export { removePlugin } from './lib/remove-plugin.js';
+export { configure } from './lib/configure.js';
+export { setupMcp, listAgentIds } from './lib/setup-mcp.js';
+export type { ProgressEvent, ProgressCallback, InstallPluginOptions, InstallResult, RemovePluginOptions, RemoveResult, ConfigureOptions, ConfigureResult, FeatureAction, McpFeatureSnapshot, SetupMcpOptions, SetupMcpResult, McpTransport, } from './lib/types.js';

package/dist/lib.js

@@ -0,0 +1,18 @@
+// Library entry point for `unity-mcp-cli`.
+//
+// Constraints (enforced by review — see issue #678):
+// - NO top-level side effects. Importing this file must not open
+//   sockets, spin up spinners, write to stdout/stderr, or parse argv.
+// - NO `commander` import reachable from this file.
+// - Errors are returned in `{ success: false, error }` results — never
+//   thrown past the public boundary.
+// - Progress is surfaced via an optional `onProgress` callback, not
+//   globals or singletons.
+//
+// Consumers: `import { installPlugin } from 'unity-mcp-cli'` (maps to
+// this file via the `exports` field in package.json).
+export { installPlugin } from './lib/install-plugin.js';
+export { removePlugin } from './lib/remove-plugin.js';
+export { configure } from './lib/configure.js';
+export { setupMcp, listAgentIds } from './lib/setup-mcp.js';
+//# sourceMappingURL=lib.js.map

package/dist/lib.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"lib.js","sourceRoot":"","sources":["../src/lib.ts"],"names":[],"mappings":"AAAA,2CAA2C;AAC3C,EAAE;AACF,qDAAqD;AACrD,iEAAiE;AACjE,sEAAsE;AACtE,oDAAoD;AACpD,uEAAuE;AACvE,qCAAqC;AACrC,oEAAoE;AACpE,2BAA2B;AAC3B,EAAE;AACF,sEAAsE;AACtE,sDAAsD;AAEtD,OAAO,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAC;AACxD,OAAO,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AACtD,OAAO,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAC/C,OAAO,EAAE,QAAQ,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC"}

package/dist/utils/manifest.d.ts

@@ -1,14 +1,28 @@
+import { type LibLogger } from '../lib/logger.js';
 /**
  * Resolve the latest plugin version from the OpenUPM registry.
  * Throws an error with actionable suggestions if the network request fails.
+ *
+ * @param logger Optional logger. Defaults to `silentLogger` so library
+ *   callers stay side-effect-free; CLI call sites must pass a chalk-
+ *   styled logger adapter explicitly to preserve the historical output.
  */
-export declare function resolveLatestVersion(): Promise<string>;
+export declare function resolveLatestVersion(logger?: LibLogger): Promise<string>;
 /**
  * Determines if the version should be updated.
  * Only update if the new version is higher than the current version.
  * Ports the C# Installer.ShouldUpdateVersion() logic.
  */
 export declare function shouldUpdateVersion(currentVersion: string, newVersion: string): boolean;
+export interface AddPluginResult {
+    /** Whether the file was modified on disk (false = already up to date). */
+    modified: boolean;
+    /** Final plugin version in the manifest (may differ from the requested
+     *  version if the existing version was higher and force was false). */
+    resolvedVersion: string;
+    /** Absolute path to the manifest.json that was inspected / written. */
+    manifestPath: string;
+}
 /**
  * Add Unity-MCP plugin to a Unity project's Packages/manifest.json.
  * Ports the C# Installer.Manifest.cs logic:
@@ -16,11 +30,25 @@ export declare function shouldUpdateVersion(currentVersion: string, newVersion:
  * - Adds/updates the plugin dependency
  * - When force is false (auto-resolved version): never downgrades
  * - When force is true (user-specified --plugin-version): allows downgrade
+ *
+ * @param logger Optional logger. Defaults to `silentLogger` so library
+ *   callers stay side-effect-free; CLI call sites must pass a chalk-
+ *   styled logger adapter explicitly to preserve the historical output.
  */
-export declare function addPluginToManifest(projectPath: string, version: string, force?: boolean): void;
+export declare function addPluginToManifest(projectPath: string, version: string, force?: boolean, logger?: LibLogger): AddPluginResult;
+export interface RemovePluginResult {
+    /** Whether the plugin was present and has been removed. */
+    removed: boolean;
+    /** Absolute path to the manifest.json that was inspected. */
+    manifestPath: string;
+}
 /**
  * Remove Unity-MCP plugin from a Unity project's Packages/manifest.json.
  * Only removes the plugin dependency — scoped registries and scopes are
  * left untouched because other packages may depend on them.
+ *
+ * @param logger Optional logger. Defaults to `silentLogger` so library
+ *   callers stay side-effect-free; CLI call sites must pass a chalk-
+ *   styled logger adapter explicitly to preserve the historical output.
  */
-export declare function removePluginFromManifest(projectPath: string): void;
+export declare function removePluginFromManifest(projectPath: string, logger?: LibLogger): RemovePluginResult;