godot-cli 0.13.3 → 0.14.0

package/CHANGELOG.md

@@ -2,6 +2,18 @@
 
 All notable changes to `godot-cli` are documented in this file.
 
+## Unreleased
+
+- `install-extension <id> [path]` — install a Godot-MCP **extension** (an optional AI-tool-family package)
+  into a Godot C# project: resolve `<id>` from the shared catalog, add/update its `<PackageReference>` in
+  the project `.csproj` (added when absent, version-bumped only when newer, no-op when up to date), then
+  ask the user to rebuild. Idempotent and behaviorally identical to the in-editor Extensions dock.
+- Added `installExtension` to the library API, plus the shared `EXTENSIONS_CATALOG` + `findExtension`
+  exports so the app can render/install the same list the dock + CLI use.
+- The extension catalog (`addons/godot_mcp/extensions.catalog.json`) is now the single source of truth
+  consumed by all three channels: the dock parses it via an embedded resource, the CLI mirrors it
+  (`extensions-catalog.ts`, parity-tested), and the app imports it from the `godot-cli` library.
+
 ## 0.1.0
 
 Initial release. A cross-platform CLI for Godot-MCP, mirroring `unity-mcp-cli`'s feature set and structure,

package/README.md

@@ -36,6 +36,7 @@ Requires Node `^20.19.0 || >=22.12.0`.
 | `configure [path]` | List / enable / disable tools, prompts, and resources in the project-local `.godot-mcp/features.json`. |
 | `close [path]` | Gracefully stop the Godot editor running for a project (`--force` to hard-kill). |
 | `install-plugin [path]` | Install the `godot_mcp` addon end-to-end: materialize `res://addons/godot_mcp/` (download the matching GitHub release, or `--source <path>` a local copy), add the required NuGet `PackageReference`s to the project `.csproj`, and enable the plugin. Idempotent. |
+| `install-extension <id> [path]` | Install a Godot-MCP **extension** (an optional AI-tool-family package) into the project: resolve `<id>` from the shared catalog, add/update its `<PackageReference>` in the project `.csproj`, then rebuild to restore. Idempotent — behaviorally identical to the in-editor dock. |
 | `remove-plugin [path]` | Disable the `godot_mcp` addon in `project.godot` `[editor_plugins]` (does not delete the addon files). |
 | `update` | Check npm for a newer `godot-cli` and install it. |
 
@@ -141,12 +142,41 @@ It performs three steps:
 It is library-safe (returns a `{ kind: 'success' | 'failure' }` union; never throws past the public
 boundary) and idempotent — re-running on an already-installed project reports no change.
 
+## `install-extension`
+
+`godot-cli install-extension <id> [path]` installs an optional Godot-MCP **extension** (a package that
+adds more AI tool families) into a Godot C# project — the terminal/library channel for the same install
+the in-editor **Extensions** dock performs:
+
+```bash
+godot-cli install-extension com.IvanMurzak.Godot.MCP.ProBuilder ./MyGodotProject   # add/update the PackageReference
+godot-cli install-extension "ProBuilder Tools"                                      # resolve by name; default cwd
+godot-cli install-extension com.IvanMurzak.Godot.MCP.ProBuilder --version 1.3.0     # override the catalog pin
+```
+
+- Resolves `<id>` against the **shared extension catalog** (`addons/godot_mcp/extensions.catalog.json` —
+  the single source of truth the dock, the CLI, and the app all consume), matching by package id (then
+  name), case-insensitive.
+- Read-modify-writes a `<PackageReference Include="<packageId>" Version="<version>" />` into the project's
+  root `.csproj`: **added** when absent, version **bumped** only when the catalog (or `--version`) pins a
+  newer version, and a **no-op** when already up to date — then asks you to rebuild (`godot-cli build`) so
+  Godot restores + compiles the new package.
+- Behaviorally identical to the dock's `ExtensionInstaller` (the same add / update / no-op + numeric
+  version-compare rules; verified by a shared scenario set on both sides).
+
+> The catalog ships **empty** until the first Godot-MCP extension package is published, so every `<id>` is
+> currently reported as an unknown extension — there is nothing to install yet.
+
 ## Library API
 
 The package also exports a side-effect-free library (the `.` entry):
 
 ```ts
-import { openProject, runTool, setupMcp, installPlugin } from 'godot-cli';
+import { openProject, runTool, setupMcp, installPlugin, installExtension } from 'godot-cli';
+
+// The shared extension catalog + lookup helpers are exported too, so a GUI (the app)
+// can render the same list the dock + CLI install from:
+import { EXTENSIONS_CATALOG, findExtension } from 'godot-cli';
 ```
 
 Every function returns a discriminated union (`{ kind: 'success', ... }` / `{ kind: 'failure', error }`)

package/dist/commands/install-extension.d.ts

@@ -0,0 +1,2 @@
+import { Command } from 'commander';
+export declare const installExtensionCommand: Command;

package/dist/commands/install-extension.js

@@ -0,0 +1,63 @@
+import { Command } from 'commander';
+import * as path from 'path';
+import * as ui from '../utils/ui.js';
+import { verbose } from '../utils/ui.js';
+import { installExtension } from '../lib/install-extension.js';
+export const installExtensionCommand = new Command('install-extension')
+    .description('Install a Godot-MCP extension into a Godot C# project: resolve the extension <id> from the shared catalog, add (or update) its <PackageReference> in the project .csproj, then rebuild to restore it. Idempotent. The project path defaults to the current directory (like install-plugin).')
+    .argument('<id>', 'Extension id to install (the package id, or the extension name)')
+    .argument('[path]', 'Path to the Godot project (defaults to the current directory)')
+    .option('--path <path>', 'Path to the Godot project')
+    .option('--version <x.y.z>', 'Override the catalog-pinned version to install')
+    .action(async (id, positionalPath, options) => {
+    const resolvedPath = positionalPath ?? options.path ?? process.cwd();
+    const projectPath = path.resolve(resolvedPath);
+    ui.heading('Installing Godot-MCP extension');
+    verbose(`Extension id: ${id}`);
+    verbose(`Project path: ${projectPath}`);
+    if (options.version)
+        verbose(`--version: ${options.version}`);
+    const spinner = ui.startSpinner('Installing extension...');
+    const result = await installExtension({
+        godotProjectPath: projectPath,
+        extensionId: id,
+        version: options.version,
+    });
+    if (result.kind === 'failure') {
+        spinner.error('Failed to install extension');
+        ui.error(result.error.message);
+        for (const warning of result.warnings) {
+            console.log('');
+            ui.warn(warning);
+        }
+        process.exit(1);
+    }
+    switch (result.outcome) {
+        case 'added':
+            spinner.success(`Installed ${result.packageId}`);
+            break;
+        case 'updated':
+            spinner.success(`Updated ${result.packageId} to ${result.toVersion}`);
+            break;
+        case 'already-up-to-date':
+            spinner.success(`${result.packageId} is already up to date`);
+            break;
+        case 'no-project':
+            // A no-project result is a kind:'success' outcome (exit 0) — use the success
+            // indicator so the spinner doesn't show a red error contradicting the exit code.
+            // The explanation is surfaced once below via ui.label('Status', result.message).
+            spinner.success('No project .csproj found — nothing to install');
+            break;
+    }
+    ui.label('Status', result.message);
+    if (result.csprojPath)
+        ui.label('Project .csproj', result.csprojPath);
+    if (result.rebuildRequired) {
+        ui.label('Next step', 'Rebuild solutions (e.g. `godot-cli build`) to restore + compile the extension.');
+    }
+    for (const warning of result.warnings) {
+        console.log('');
+        ui.warn(warning);
+    }
+});
+//# sourceMappingURL=install-extension.js.map

package/dist/commands/install-extension.js.map

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

package/dist/index.js

@@ -13,6 +13,7 @@ import { createProjectCommand } from './commands/create-project.js';
 import { closeCommand } from './commands/close.js';
 import { createUpdateCommand } from './commands/update.js';
 import { installPluginCommand } from './commands/install-plugin.js';
+import { installExtensionCommand } from './commands/install-extension.js';
 import { removePluginCommand } from './commands/remove-plugin.js';
 import { configureStyledHelp, error as uiError, setVerbose } from './utils/ui.js';
 import { checkForUpdate, isRunningViaNpx, printUpdateNotification } from './utils/update-check.js';
@@ -31,6 +32,7 @@ const subcommands = [
     configureCommand,
     createProjectCommand,
     installPluginCommand,
+    installExtensionCommand,
     openCommand,
     removePluginCommand,
     runToolCommand,

package/dist/index.js.map

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

package/dist/lib/install-extension.d.ts

@@ -0,0 +1,20 @@
+import type { InstallExtensionOptions, InstallExtensionResult } from './types.js';
+/**
+ * Install (or update) a Godot-MCP extension into a consumer Godot C# project, as a
+ * REAL installer that is behaviorally identical to the in-editor dock's
+ * `ExtensionInstaller`:
+ *
+ *  1. Resolve `extensionId` to a descriptor in the SHARED catalog
+ *     (`addons/godot_mcp/extensions.catalog.json`, mirrored by `EXTENSIONS_CATALOG`).
+ *  2. Locate the consumer `.csproj` at the project root.
+ *  3. Read-modify-write a `<PackageReference Include="<packageId>" Version="<version>" />`
+ *     into it — added when absent, version-bumped only when the catalog (or `--version`)
+ *     pins a NEWER version, and a no-op when already up to date.
+ *  4. Tell the caller a rebuild is required (Godot has no programmatic restore).
+ *
+ * Library-safe: no stdout noise, no `process.exit`, no throws past the public boundary;
+ * returns a `{ kind: 'success' | 'failure' }` union. Idempotent: a re-run that finds the
+ * reference present at an equal/newer version reports `already-up-to-date` and makes no
+ * write. Mirrors `installPlugin`'s shape exactly so the app can adopt it the same way.
+ */
+export declare function installExtension(opts: InstallExtensionOptions): Promise<InstallExtensionResult>;

package/dist/lib/install-extension.js

@@ -0,0 +1,183 @@
+import * as fs from 'fs';
+import * as path from 'path';
+import { EXTENSIONS_CATALOG, findExtension, hasVersion, } from '../utils/extensions-catalog.js';
+import { planExtensionInstall, CsprojParseError, } from '../utils/extension-install.js';
+import { emitProgress } from './progress.js';
+import { requireGodotProject } from './validation.js';
+/**
+ * Install (or update) a Godot-MCP extension into a consumer Godot C# project, as a
+ * REAL installer that is behaviorally identical to the in-editor dock's
+ * `ExtensionInstaller`:
+ *
+ *  1. Resolve `extensionId` to a descriptor in the SHARED catalog
+ *     (`addons/godot_mcp/extensions.catalog.json`, mirrored by `EXTENSIONS_CATALOG`).
+ *  2. Locate the consumer `.csproj` at the project root.
+ *  3. Read-modify-write a `<PackageReference Include="<packageId>" Version="<version>" />`
+ *     into it — added when absent, version-bumped only when the catalog (or `--version`)
+ *     pins a NEWER version, and a no-op when already up to date.
+ *  4. Tell the caller a rebuild is required (Godot has no programmatic restore).
+ *
+ * Library-safe: no stdout noise, no `process.exit`, no throws past the public boundary;
+ * returns a `{ kind: 'success' | 'failure' }` union. Idempotent: a re-run that finds the
+ * reference present at an equal/newer version reports `already-up-to-date` and makes no
+ * write. Mirrors `installPlugin`'s shape exactly so the app can adopt it the same way.
+ */
+export async function installExtension(opts) {
+    const warnings = [];
+    try {
+        const validated = requireGodotProject(opts?.godotProjectPath);
+        if (!validated.ok) {
+            return {
+                kind: 'failure',
+                success: false,
+                projectGodotPath: validated.projectGodotPath,
+                warnings,
+                error: validated.error,
+            };
+        }
+        const { projectPath } = validated;
+        const catalog = opts.catalog ?? EXTENSIONS_CATALOG;
+        const resolved = findExtension(opts.extensionId, catalog);
+        if (resolved === null) {
+            return {
+                kind: 'failure',
+                success: false,
+                warnings,
+                error: new Error(unknownExtensionMessage(opts.extensionId, catalog)),
+            };
+        }
+        // Apply the optional --version override (drives both the pin written and the bump decision).
+        const descriptor = applyVersionOverride(resolved, opts.version, warnings);
+        emitProgress(opts.onProgress, {
+            phase: 'start',
+            message: `Installing extension ${descriptor.packageId}${hasVersion(descriptor) ? ` ${descriptor.version}` : ''} into ${projectPath}`,
+        });
+        const csprojPath = findConsumerCsproj(projectPath, warnings);
+        if (csprojPath === null) {
+            const message = 'No project .csproj found at the project root — open this addon inside a Godot C# project to install extensions. ' +
+                `Create one (e.g. \`godot-cli create-project --dotnet\`) and add the ${descriptor.packageId} PackageReference.`;
+            emitProgress(opts.onProgress, { phase: 'done', message: 'No project .csproj — nothing installed.' });
+            return {
+                kind: 'success',
+                success: true,
+                outcome: 'no-project',
+                changed: false,
+                rebuildRequired: false,
+                extensionId: opts.extensionId,
+                packageId: descriptor.packageId,
+                fromVersion: null,
+                toVersion: hasVersion(descriptor) ? descriptor.version : null,
+                message,
+                warnings,
+            };
+        }
+        const before = fs.readFileSync(csprojPath, 'utf-8');
+        let plan;
+        try {
+            plan = planExtensionInstall(descriptor, before);
+        }
+        catch (err) {
+            if (err instanceof CsprojParseError) {
+                return {
+                    kind: 'failure',
+                    success: false,
+                    warnings,
+                    error: new Error(`Could not edit the project .csproj: ${err.message}`),
+                };
+            }
+            throw err;
+        }
+        if (plan.action === 'noop') {
+            emitProgress(opts.onProgress, { phase: 'done', message: `${descriptor.packageId} is already up to date.` });
+            return {
+                kind: 'success',
+                success: true,
+                outcome: 'already-up-to-date',
+                changed: false,
+                rebuildRequired: false,
+                extensionId: opts.extensionId,
+                packageId: descriptor.packageId,
+                fromVersion: plan.fromVersion,
+                toVersion: plan.toVersion,
+                csprojPath,
+                message: `${descriptor.name} is already installed and up to date.`,
+                warnings,
+            };
+        }
+        fs.writeFileSync(csprojPath, plan.resultingCsproj);
+        emitProgress(opts.onProgress, {
+            phase: 'csproj-patched',
+            message: `${plan.action === 'add' ? 'Added' : 'Updated'} ${descriptor.packageId} in ${csprojPath}`,
+            csprojPath,
+        });
+        emitProgress(opts.onProgress, { phase: 'done', message: 'Extension installed — rebuild solutions to restore.' });
+        const message = plan.action === 'add'
+            ? `Added ${descriptor.packageId}${hasVersion(descriptor) ? ` ${descriptor.version}` : ''}. Rebuild solutions to restore and compile the extension.`
+            : `Updated ${descriptor.packageId} to ${plan.toVersion}. Rebuild solutions to restore the new version.`;
+        return {
+            kind: 'success',
+            success: true,
+            outcome: plan.action === 'add' ? 'added' : 'updated',
+            changed: true,
+            rebuildRequired: true,
+            extensionId: opts.extensionId,
+            packageId: descriptor.packageId,
+            fromVersion: plan.fromVersion,
+            toVersion: plan.toVersion,
+            csprojPath,
+            message,
+            warnings,
+        };
+    }
+    catch (err) {
+        return {
+            kind: 'failure',
+            success: false,
+            warnings,
+            error: err instanceof Error ? err : new Error(String(err)),
+        };
+    }
+}
+/** Return a descriptor with the `--version` override applied (empty/whitespace override is ignored). */
+function applyVersionOverride(descriptor, version, warnings) {
+    const v = (version ?? '').trim();
+    if (v === '')
+        return descriptor;
+    if (descriptor.version !== null && descriptor.version !== v) {
+        warnings.push(`--version ${v} overrides the catalog pin ${descriptor.packageId}@${descriptor.version} for this install.`);
+    }
+    return { ...descriptor, version: v };
+}
+/** A clear "unknown extension" error that lists what IS installable (or says the catalog is empty). */
+function unknownExtensionMessage(id, catalog) {
+    if (catalog.length === 0) {
+        return (`Unknown extension "${id}". The Godot-MCP extension catalog is currently empty ` +
+            '(no extension packages have been published yet), so there is nothing to install.');
+    }
+    const available = catalog.map((d) => d.packageId).join(', ');
+    return `Unknown extension "${id}". Available extensions: ${available}.`;
+}
+/**
+ * Find the consumer's `.csproj` (the one Godot compiles every `.cs` into) — the single
+ * `*.csproj` at the project root. When several exist, pick the first alphabetically and
+ * warn (they all compile into the same Godot assembly). Returns null when none exist
+ * (a GDScript-only project). Mirrors `install-plugin`'s `findConsumerCsproj`.
+ */
+function findConsumerCsproj(projectPath, warnings) {
+    let names;
+    try {
+        names = fs.readdirSync(projectPath).filter((n) => n.toLowerCase().endsWith('.csproj'));
+    }
+    catch {
+        return null;
+    }
+    if (names.length === 0)
+        return null;
+    names.sort();
+    if (names.length > 1) {
+        warnings.push(`Multiple .csproj files found at the project root (${names.join(', ')}); patched ${names[0]}. ` +
+            'If a different one is the Godot project, add the extension PackageReference to it as well.');
+    }
+    return path.join(projectPath, names[0]);
+}
+//# sourceMappingURL=install-extension.js.map

package/dist/lib/install-extension.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"install-extension.js","sourceRoot":"","sources":["../../src/lib/install-extension.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,IAAI,CAAC;AACzB,OAAO,KAAK,IAAI,MAAM,MAAM,CAAC;AAC7B,OAAO,EACL,kBAAkB,EAClB,aAAa,EACb,UAAU,GAEX,MAAM,gCAAgC,CAAC;AACxC,OAAO,EACL,oBAAoB,EACpB,gBAAgB,GAEjB,MAAM,+BAA+B,CAAC;AACvC,OAAO,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAC7C,OAAO,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAC;AAMtD;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,CAAC,KAAK,UAAU,gBAAgB,CACpC,IAA6B;IAE7B,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,IAAI,EAAE,SAAS;gBACf,OAAO,EAAE,KAAK;gBACd,gBAAgB,EAAE,SAAS,CAAC,gBAAgB;gBAC5C,QAAQ;gBACR,KAAK,EAAE,SAAS,CAAC,KAAK;aACvB,CAAC;QACJ,CAAC;QACD,MAAM,EAAE,WAAW,EAAE,GAAG,SAAS,CAAC;QAElC,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,IAAI,kBAAkB,CAAC;QACnD,MAAM,QAAQ,GAAG,aAAa,CAAC,IAAI,CAAC,WAAW,EAAE,OAAO,CAAC,CAAC;QAC1D,IAAI,QAAQ,KAAK,IAAI,EAAE,CAAC;YACtB,OAAO;gBACL,IAAI,EAAE,SAAS;gBACf,OAAO,EAAE,KAAK;gBACd,QAAQ;gBACR,KAAK,EAAE,IAAI,KAAK,CAAC,uBAAuB,CAAC,IAAI,CAAC,WAAW,EAAE,OAAO,CAAC,CAAC;aACrE,CAAC;QACJ,CAAC;QAED,6FAA6F;QAC7F,MAAM,UAAU,GAAG,oBAAoB,CAAC,QAAQ,EAAE,IAAI,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC;QAE1E,YAAY,CAAC,IAAI,CAAC,UAAU,EAAE;YAC5B,KAAK,EAAE,OAAO;YACd,OAAO,EAAE,wBAAwB,UAAU,CAAC,SAAS,GAAG,UAAU,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,IAAI,UAAU,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,SAAS,WAAW,EAAE;SACrI,CAAC,CAAC;QAEH,MAAM,UAAU,GAAG,kBAAkB,CAAC,WAAW,EAAE,QAAQ,CAAC,CAAC;QAC7D,IAAI,UAAU,KAAK,IAAI,EAAE,CAAC;YACxB,MAAM,OAAO,GACX,kHAAkH;gBAClH,uEAAuE,UAAU,CAAC,SAAS,oBAAoB,CAAC;YAClH,YAAY,CAAC,IAAI,CAAC,UAAU,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,yCAAyC,EAAE,CAAC,CAAC;YACrG,OAAO;gBACL,IAAI,EAAE,SAAS;gBACf,OAAO,EAAE,IAAI;gBACb,OAAO,EAAE,YAAY;gBACrB,OAAO,EAAE,KAAK;gBACd,eAAe,EAAE,KAAK;gBACtB,WAAW,EAAE,IAAI,CAAC,WAAW;gBAC7B,SAAS,EAAE,UAAU,CAAC,SAAS;gBAC/B,WAAW,EAAE,IAAI;gBACjB,SAAS,EAAE,UAAU,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI;gBAC7D,OAAO;gBACP,QAAQ;aACT,CAAC;QACJ,CAAC;QAED,MAAM,MAAM,GAAG,EAAE,CAAC,YAAY,CAAC,UAAU,EAAE,OAAO,CAAC,CAAC;QACpD,IAAI,IAA0B,CAAC;QAC/B,IAAI,CAAC;YACH,IAAI,GAAG,oBAAoB,CAAC,UAAU,EAAE,MAAM,CAAC,CAAC;QAClD,CAAC;QAAC,OAAO,GAAY,EAAE,CAAC;YACtB,IAAI,GAAG,YAAY,gBAAgB,EAAE,CAAC;gBACpC,OAAO;oBACL,IAAI,EAAE,SAAS;oBACf,OAAO,EAAE,KAAK;oBACd,QAAQ;oBACR,KAAK,EAAE,IAAI,KAAK,CAAC,uCAAuC,GAAG,CAAC,OAAO,EAAE,CAAC;iBACvE,CAAC;YACJ,CAAC;YACD,MAAM,GAAG,CAAC;QACZ,CAAC;QAED,IAAI,IAAI,CAAC,MAAM,KAAK,MAAM,EAAE,CAAC;YAC3B,YAAY,CAAC,IAAI,CAAC,UAAU,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,GAAG,UAAU,CAAC,SAAS,yBAAyB,EAAE,CAAC,CAAC;YAC5G,OAAO;gBACL,IAAI,EAAE,SAAS;gBACf,OAAO,EAAE,IAAI;gBACb,OAAO,EAAE,oBAAoB;gBAC7B,OAAO,EAAE,KAAK;gBACd,eAAe,EAAE,KAAK;gBACtB,WAAW,EAAE,IAAI,CAAC,WAAW;gBAC7B,SAAS,EAAE,UAAU,CAAC,SAAS;gBAC/B,WAAW,EAAE,IAAI,CAAC,WAAW;gBAC7B,SAAS,EAAE,IAAI,CAAC,SAAS;gBACzB,UAAU;gBACV,OAAO,EAAE,GAAG,UAAU,CAAC,IAAI,uCAAuC;gBAClE,QAAQ;aACT,CAAC;QACJ,CAAC;QAED,EAAE,CAAC,aAAa,CAAC,UAAU,EAAE,IAAI,CAAC,eAAe,CAAC,CAAC;QACnD,YAAY,CAAC,IAAI,CAAC,UAAU,EAAE;YAC5B,KAAK,EAAE,gBAAgB;YACvB,OAAO,EAAE,GAAG,IAAI,CAAC,MAAM,KAAK,KAAK,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,SAAS,IAAI,UAAU,CAAC,SAAS,OAAO,UAAU,EAAE;YAClG,UAAU;SACX,CAAC,CAAC;QACH,YAAY,CAAC,IAAI,CAAC,UAAU,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,qDAAqD,EAAE,CAAC,CAAC;QAEjH,MAAM,OAAO,GACX,IAAI,CAAC,MAAM,KAAK,KAAK;YACnB,CAAC,CAAC,SAAS,UAAU,CAAC,SAAS,GAAG,UAAU,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,IAAI,UAAU,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,2DAA2D;YACnJ,CAAC,CAAC,WAAW,UAAU,CAAC,SAAS,OAAO,IAAI,CAAC,SAAS,iDAAiD,CAAC;QAE5G,OAAO;YACL,IAAI,EAAE,SAAS;YACf,OAAO,EAAE,IAAI;YACb,OAAO,EAAE,IAAI,CAAC,MAAM,KAAK,KAAK,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,SAAS;YACpD,OAAO,EAAE,IAAI;YACb,eAAe,EAAE,IAAI;YACrB,WAAW,EAAE,IAAI,CAAC,WAAW;YAC7B,SAAS,EAAE,UAAU,CAAC,SAAS;YAC/B,WAAW,EAAE,IAAI,CAAC,WAAW;YAC7B,SAAS,EAAE,IAAI,CAAC,SAAS;YACzB,UAAU;YACV,OAAO;YACP,QAAQ;SACT,CAAC;IACJ,CAAC;IAAC,OAAO,GAAY,EAAE,CAAC;QACtB,OAAO;YACL,IAAI,EAAE,SAAS;YACf,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;AAED,wGAAwG;AACxG,SAAS,oBAAoB,CAC3B,UAA+B,EAC/B,OAA2B,EAC3B,QAAkB;IAElB,MAAM,CAAC,GAAG,CAAC,OAAO,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;IACjC,IAAI,CAAC,KAAK,EAAE;QAAE,OAAO,UAAU,CAAC;IAChC,IAAI,UAAU,CAAC,OAAO,KAAK,IAAI,IAAI,UAAU,CAAC,OAAO,KAAK,CAAC,EAAE,CAAC;QAC5D,QAAQ,CAAC,IAAI,CACX,aAAa,CAAC,8BAA8B,UAAU,CAAC,SAAS,IAAI,UAAU,CAAC,OAAO,oBAAoB,CAC3G,CAAC;IACJ,CAAC;IACD,OAAO,EAAE,GAAG,UAAU,EAAE,OAAO,EAAE,CAAC,EAAE,CAAC;AACvC,CAAC;AAED,uGAAuG;AACvG,SAAS,uBAAuB,CAC9B,EAAU,EACV,OAAuC;IAEvC,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACzB,OAAO,CACL,sBAAsB,EAAE,wDAAwD;YAChF,kFAAkF,CACnF,CAAC;IACJ,CAAC;IACD,MAAM,SAAS,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAC7D,OAAO,sBAAsB,EAAE,4BAA4B,SAAS,GAAG,CAAC;AAC1E,CAAC;AAED;;;;;GAKG;AACH,SAAS,kBAAkB,CAAC,WAAmB,EAAE,QAAkB;IACjE,IAAI,KAAe,CAAC;IACpB,IAAI,CAAC;QACH,KAAK,GAAG,EAAE,CAAC,WAAW,CAAC,WAAW,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,WAAW,EAAE,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAC,CAAC;IACzF,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;IACD,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IACpC,KAAK,CAAC,IAAI,EAAE,CAAC;IACb,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACrB,QAAQ,CAAC,IAAI,CACX,qDAAqD,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,cAAc,KAAK,CAAC,CAAC,CAAC,IAAI;YAC7F,4FAA4F,CAC/F,CAAC;IACJ,CAAC;IACD,OAAO,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;AAC1C,CAAC"}

package/dist/lib/types.d.ts

@@ -1,3 +1,4 @@
+import type { ExtensionDescriptor } from '../utils/extensions-catalog.js';
 /**
  * Discriminated union describing every progress event the library can emit to
  * the optional `onProgress` callback. Consumers narrow on `event.phase`.
@@ -415,3 +416,57 @@ export interface RemovePluginFailure {
     error: Error;
 }
 export type RemovePluginResult = RemovePluginSuccess | RemovePluginFailure;
+/**
+ * What `installExtension` did to the consumer `.csproj` — the CLI mirror of the dock's
+ * `ExtensionInstallOutcome`:
+ *  - `added`             — the `<PackageReference>` was newly added (rebuild required).
+ *  - `updated`           — its version was bumped up (rebuild required).
+ *  - `already-up-to-date`— present at an equal/newer version, or the descriptor has no pin (no write).
+ *  - `no-project`        — no consumer `.csproj` was found to install into (nothing written).
+ */
+export type ExtensionInstallOutcome = 'added' | 'updated' | 'already-up-to-date' | 'no-project';
+export interface InstallExtensionOptions {
+    /** Absolute or relative path to the Godot project root (holds `project.godot` + the consumer `.csproj`). */
+    godotProjectPath: string;
+    /** The extension `<id>` to install — matched against the catalog by `packageId` (then `name`), case-insensitive. */
+    extensionId: string;
+    /** Override the catalog's pinned version for this install (the `--version` flag). Ignored when empty. */
+    version?: string;
+    /**
+     * Catalog to resolve `extensionId` against. Defaults to the bundled `EXTENSIONS_CATALOG`
+     * (single-sourced from `addons/godot_mcp/extensions.catalog.json`). Injectable for tests.
+     */
+    catalog?: readonly ExtensionDescriptor[];
+    onProgress?: ProgressCallback;
+}
+export interface InstallExtensionSuccess {
+    kind: 'success';
+    success: true;
+    /** The classified outcome (added / updated / already-up-to-date / no-project). */
+    outcome: ExtensionInstallOutcome;
+    /** True when the `.csproj` was written (added or updated). */
+    changed: boolean;
+    /** True when a write happened, so the consumer must rebuild solutions (Godot has no programmatic restore). */
+    rebuildRequired: boolean;
+    /** The user-supplied id that resolved to the descriptor. */
+    extensionId: string;
+    /** The resolved descriptor's package id (the `<PackageReference Include>`). */
+    packageId: string;
+    /** Version currently referenced before this install: `null` when not installed, `''` when referenced unversioned. */
+    fromVersion: string | null;
+    /** The version this install targeted (catalog pin or `--version` override), or `null` when unpinned. */
+    toVersion: string | null;
+    /** Absolute path to the consumer `.csproj`, when one was located. */
+    csprojPath?: string;
+    /** A short human-readable status line, safe to print. */
+    message: string;
+    warnings: string[];
+}
+export interface InstallExtensionFailure {
+    kind: 'failure';
+    success: false;
+    projectGodotPath?: string;
+    warnings: string[];
+    error: Error;
+}
+export type InstallExtensionResult = InstallExtensionSuccess | InstallExtensionFailure;

package/dist/lib.d.ts

@@ -5,4 +5,7 @@ export { runTool, runSystemTool } from './lib/run-tool.js';
 export { setupMcp, listAgentIds } from './lib/setup-mcp.js';
 export { setupSkills } from './lib/setup-skills.js';
 export { installPlugin, removePlugin } from './lib/install-plugin.js';
-export type { ProgressEvent, ProgressCallback, ResultKind, OpenProjectOptions, OpenProjectResult, OpenProjectSuccess, OpenProjectFailure, OpenProjectAuthOption, OpenProjectConnectionMode, BuildProjectOptions, BuildProjectResult, BuildProjectSuccess, BuildProjectFailure, BuildSkipReason, CreateProjectOptions, CreateProjectResult, CreateProjectSuccess, CreateProjectFailure, RunToolOptions, RunToolResult, RunToolSuccess, RunToolFailure, RunToolFailureReason, RunSystemToolOptions, RunSystemToolResult, RunSystemToolSuccess, RunSystemToolFailure, SetupMcpOptions, SetupMcpResult, SetupMcpSuccess, SetupMcpFailure, SetupSkillsOptions, SetupSkillsResult, SetupSkillsSuccess, SetupSkillsFailure, InstallPluginOptions, InstallPluginResult, InstallPluginSuccess, InstallPluginFailure, AddonMaterializeOutcome, CsprojPatchOutcome, RemovePluginOptions, RemovePluginResult, RemovePluginSuccess, RemovePluginFailure, } from './lib/types.js';
+export { installExtension } from './lib/install-extension.js';
+export { EXTENSIONS_CATALOG, findExtension, hasVersion } from './utils/extensions-catalog.js';
+export type { ExtensionDescriptor, ExtensionTool } from './utils/extensions-catalog.js';
+export type { ProgressEvent, ProgressCallback, ResultKind, OpenProjectOptions, OpenProjectResult, OpenProjectSuccess, OpenProjectFailure, OpenProjectAuthOption, OpenProjectConnectionMode, BuildProjectOptions, BuildProjectResult, BuildProjectSuccess, BuildProjectFailure, BuildSkipReason, CreateProjectOptions, CreateProjectResult, CreateProjectSuccess, CreateProjectFailure, RunToolOptions, RunToolResult, RunToolSuccess, RunToolFailure, RunToolFailureReason, RunSystemToolOptions, RunSystemToolResult, RunSystemToolSuccess, RunSystemToolFailure, SetupMcpOptions, SetupMcpResult, SetupMcpSuccess, SetupMcpFailure, SetupSkillsOptions, SetupSkillsResult, SetupSkillsSuccess, SetupSkillsFailure, InstallPluginOptions, InstallPluginResult, InstallPluginSuccess, InstallPluginFailure, AddonMaterializeOutcome, CsprojPatchOutcome, RemovePluginOptions, RemovePluginResult, RemovePluginSuccess, RemovePluginFailure, InstallExtensionOptions, InstallExtensionResult, InstallExtensionSuccess, InstallExtensionFailure, ExtensionInstallOutcome, } from './lib/types.js';

package/dist/lib.js

@@ -19,4 +19,8 @@ export { runTool, runSystemTool } from './lib/run-tool.js';
 export { setupMcp, listAgentIds } from './lib/setup-mcp.js';
 export { setupSkills } from './lib/setup-skills.js';
 export { installPlugin, removePlugin } from './lib/install-plugin.js';
+export { installExtension } from './lib/install-extension.js';
+// Shared extension catalog (single-sourced from addons/godot_mcp/extensions.catalog.json)
+// + its lookup helpers, so the app can render the same list the dock + CLI install from.
+export { EXTENSIONS_CATALOG, findExtension, hasVersion } from './utils/extensions-catalog.js';
 //# sourceMappingURL=lib.js.map

package/dist/lib.js.map

@@ -1 +1 @@
-{"version":3,"file":"lib.js","sourceRoot":"","sources":["../src/lib.ts"],"names":[],"mappings":"AAAA,uCAAuC;AACvC,EAAE;AACF,eAAe;AACf,+EAA+E;AAC/E,wDAAwD;AACxD,oDAAoD;AACpD,yEAAyE;AACzE,4DAA4D;AAC5D,+EAA+E;AAC/E,gEAAgE;AAChE,6EAA6E;AAC7E,EAAE;AACF,0EAA0E;AAC1E,4CAA4C;AAE5C,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAC5C,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAC9C,OAAO,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAC;AACxD,OAAO,EAAE,OAAO,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAC3D,OAAO,EAAE,QAAQ,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAC5D,OAAO,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AACpD,OAAO,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAC"}
+{"version":3,"file":"lib.js","sourceRoot":"","sources":["../src/lib.ts"],"names":[],"mappings":"AAAA,uCAAuC;AACvC,EAAE;AACF,eAAe;AACf,+EAA+E;AAC/E,wDAAwD;AACxD,oDAAoD;AACpD,yEAAyE;AACzE,4DAA4D;AAC5D,+EAA+E;AAC/E,gEAAgE;AAChE,6EAA6E;AAC7E,EAAE;AACF,0EAA0E;AAC1E,4CAA4C;AAE5C,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAC5C,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAC9C,OAAO,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAC;AACxD,OAAO,EAAE,OAAO,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAC3D,OAAO,EAAE,QAAQ,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAC5D,OAAO,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AACpD,OAAO,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAC;AACtE,OAAO,EAAE,gBAAgB,EAAE,MAAM,4BAA4B,CAAC;AAE9D,0FAA0F;AAC1F,yFAAyF;AACzF,OAAO,EAAE,kBAAkB,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,+BAA+B,CAAC"}

package/dist/utils/extension-install.d.ts

@@ -0,0 +1,41 @@
+import type { ExtensionDescriptor } from './extensions-catalog.js';
+export type ExtensionInstallAction = 'add' | 'update' | 'noop';
+export interface ExtensionInstallPlan {
+    /** The add / update / no-op decision. */
+    action: ExtensionInstallAction;
+    /** The full `.csproj` text after applying the action (=== input for a no-op). */
+    resultingCsproj: string;
+    /** The package id the plan targets. */
+    packageId: string;
+    /** Version currently referenced: `null` when not installed; `''` when referenced without a version. */
+    fromVersion: string | null;
+    /** The descriptor's target version, or `null` when the descriptor has no pin. */
+    toVersion: string | null;
+}
+/** Thrown by {@link planExtensionInstall} on a genuinely unparseable `.csproj` (the lib turns it into a structured failure). */
+export declare class CsprojParseError extends Error {
+}
+/**
+ * Compare two dotted numeric version strings component-by-component as integers
+ * (so `1.10.0` > `1.2.0`, unlike an ordinal string compare). A trailing pre-release
+ * / build suffix on a component (`1.0.0-rc1`) is tolerated — only the leading integer
+ * of each component is read; a non-numeric component reads as 0. Missing trailing
+ * components are treated as 0 (`1.0` === `1.0.0`). Returns >0 when `a` is newer, <0
+ * when older, 0 when equal. Exact port of C# `InstalledStateDetector.CompareVersions`.
+ */
+export declare function compareVersions(a: string, b: string): number;
+/**
+ * Parse every `<PackageReference>` in the `.csproj` into a `{ packageId → version }`
+ * map (ids lower-cased — NuGet ids are case-insensitive; value is the `Version`
+ * attribute, else a child `<Version>` element, else `''`). Returns an EMPTY map for
+ * empty/whitespace input. Port of C# `InstalledStateDetector.ParsePackageReferences`
+ * (the CLI never needs the bad-XML tolerance branch — the planner validates first).
+ */
+export declare function parsePackageReferences(csprojText: string | null | undefined): Map<string, string>;
+/**
+ * Compute the install plan for `descriptor` against `csprojText`. Port of
+ * `ExtensionInstallPlanner.Plan`. Throws {@link CsprojParseError} only on a genuinely
+ * malformed `.csproj` (no recognizable `<Project ...>` root) — the caller maps that to
+ * a structured failure rather than corrupting the file.
+ */
+export declare function planExtensionInstall(descriptor: ExtensionDescriptor, csprojText: string): ExtensionInstallPlan;

package/dist/utils/extension-install.js

@@ -0,0 +1,223 @@
+// Pure, behaviorally-identical TS port of the dock's extension-install logic
+// (`addons/godot_mcp/Runtime/Extensions/ExtensionInstallPlanner.cs` +
+// `InstalledStateDetector.CompareVersions`). It computes the add / update / no-op
+// plan AND the resulting `.csproj` text from a descriptor + the current `.csproj`,
+// preserving every other `<PackageReference>` and unrelated XML.
+//
+// Parity contract (verified by `cli/tests/extension-install.test.ts` against the
+// SAME scenario set as `Godot-MCP.Tests/ExtensionInstallTests.cs`):
+//   - absent reference            → ADD (append; version attribute only when pinned)
+//   - present, descriptor newer   → UPDATE (bump version, honoring attr vs child form)
+//   - present, no version, pinned → UPDATE (set the descriptor's pin)
+//   - present, equal/newer        → NO-OP
+//   - descriptor unpinned, present→ NO-OP
+//   - version compare is numeric + tolerant (1.10.0 > 1.2.0; trailing 0; suffix-tolerant)
+//
+// The C# planner uses System.Xml.Linq; this uses scoped text edits (like the CLI's
+// existing `csproj-deps.ts`) so the consumer's formatting is preserved verbatim. The
+// add/update/no-op DECISION and the resulting parsed PackageReferences are identical.
+//
+// No top-level side effects; pure string transforms only.
+import { hasVersion } from './extensions-catalog.js';
+/** Thrown by {@link planExtensionInstall} on a genuinely unparseable `.csproj` (the lib turns it into a structured failure). */
+export class CsprojParseError extends Error {
+}
+/** Escape a string for use inside a RegExp source. */
+function escapeRegExp(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+/**
+ * Compare two dotted numeric version strings component-by-component as integers
+ * (so `1.10.0` > `1.2.0`, unlike an ordinal string compare). A trailing pre-release
+ * / build suffix on a component (`1.0.0-rc1`) is tolerated — only the leading integer
+ * of each component is read; a non-numeric component reads as 0. Missing trailing
+ * components are treated as 0 (`1.0` === `1.0.0`). Returns >0 when `a` is newer, <0
+ * when older, 0 when equal. Exact port of C# `InstalledStateDetector.CompareVersions`.
+ */
+export function compareVersions(a, b) {
+    const pa = splitComponents(a);
+    const pb = splitComponents(b);
+    const n = Math.max(pa.length, pb.length);
+    for (let i = 0; i < n; i++) {
+        const ca = i < pa.length ? pa[i] : 0;
+        const cb = i < pb.length ? pb[i] : 0;
+        if (ca !== cb)
+            return ca < cb ? -1 : 1;
+    }
+    return 0;
+}
+function splitComponents(version) {
+    if (version === null || version === undefined || version.trim() === '')
+        return [];
+    return version
+        .trim()
+        .split('.')
+        .map((part) => leadingInt(part));
+}
+function leadingInt(component) {
+    let end = 0;
+    while (end < component.length && component[end] >= '0' && component[end] <= '9')
+        end++;
+    if (end === 0)
+        return 0;
+    const value = Number.parseInt(component.slice(0, end), 10);
+    return Number.isNaN(value) ? 0 : value;
+}
+/**
+ * Parse every `<PackageReference>` in the `.csproj` into a `{ packageId → version }`
+ * map (ids lower-cased — NuGet ids are case-insensitive; value is the `Version`
+ * attribute, else a child `<Version>` element, else `''`). Returns an EMPTY map for
+ * empty/whitespace input. Port of C# `InstalledStateDetector.ParsePackageReferences`
+ * (the CLI never needs the bad-XML tolerance branch — the planner validates first).
+ */
+export function parsePackageReferences(csprojText) {
+    const map = new Map();
+    if (csprojText === null || csprojText === undefined || csprojText.trim() === '')
+        return map;
+    const elementRe = /<PackageReference\b[^>]*?(?:\/>|>[\s\S]*?<\/PackageReference>)/gi;
+    let m;
+    while ((m = elementRe.exec(csprojText)) !== null) {
+        const element = m[0];
+        const include = /\bInclude\s*=\s*"([^"]*)"/i.exec(element);
+        if (!include || include[1].trim() === '')
+            continue;
+        map.set(include[1].trim().toLowerCase(), readElementVersion(element));
+    }
+    return map;
+}
+/** Read the version off a single matched `<PackageReference>` element (attribute form, else child element; `''` when unversioned). */
+function readElementVersion(element) {
+    const attr = /\bVersion\s*=\s*"([^"]*)"/i.exec(element);
+    if (attr && attr[1].trim() !== '')
+        return attr[1].trim();
+    const child = /<Version>\s*([^<]*?)\s*<\/Version>/i.exec(element);
+    if (child)
+        return child[1].trim();
+    return '';
+}
+/** Match the whole `<PackageReference>` element (either attribute order, self-close or open/close) for one id. */
+function packageRefElementRegex(id) {
+    const escId = escapeRegExp(id);
+    return new RegExp(`<PackageReference\\b[^>]*?\\bInclude\\s*=\\s*"${escId}"[^>]*?(?:/>|>[\\s\\S]*?</PackageReference>)`, 'i');
+}
+function detectIndent(text) {
+    const m = text.match(/\n([ \t]*)<PackageReference\b/);
+    return m ? m[1] : '    ';
+}
+function detectEol(text) {
+    const crlf = (text.match(/\r\n/g) ?? []).length;
+    const lf = (text.match(/\n/g) ?? []).length - crlf;
+    return crlf > lf ? '\r\n' : '\n';
+}
+function renderRef(descriptor) {
+    return hasVersion(descriptor)
+        ? `<PackageReference Include="${descriptor.packageId}" Version="${descriptor.version}" />`
+        : `<PackageReference Include="${descriptor.packageId}" />`;
+}
+/** Index of the `</ItemGroup>` closing the FIRST `<ItemGroup>` holding a `<PackageReference>`, or -1. */
+function findPackageReferenceItemGroupClose(text) {
+    const itemGroupRe = /<ItemGroup\b[^>]*>([\s\S]*?)<\/ItemGroup>/gi;
+    let m;
+    while ((m = itemGroupRe.exec(text)) !== null) {
+        if (/<PackageReference\b/i.test(m[1])) {
+            const closeTag = '</ItemGroup>';
+            return m.index + m[0].length - closeTag.length;
+        }
+    }
+    return -1;
+}
+/** Append a new `<PackageReference>` for the descriptor, joining the first package ItemGroup or a fresh one. */
+function appendReference(text, descriptor) {
+    const indent = detectIndent(text);
+    const eol = detectEol(text);
+    const element = `${indent}${renderRef(descriptor)}`;
+    const pkgItemGroupClose = findPackageReferenceItemGroupClose(text);
+    if (pkgItemGroupClose !== -1) {
+        // Insert before the START of the `</ItemGroup>` line, not at the `<` of `</ItemGroup>`
+        // itself: slicing at `pkgItemGroupClose` would absorb the closing tag's indent into the
+        // prefix, so the appended element would inherit that indent on top of its own and
+        // `</ItemGroup>` would lose its indent. Splitting at the line start keeps both aligned.
+        const lineStart = text.lastIndexOf('\n', pkgItemGroupClose) + 1;
+        return `${text.slice(0, lineStart)}${element}${eol}${text.slice(lineStart)}`;
+    }
+    const groupIndent = indent.length >= 2 ? indent.slice(0, Math.floor(indent.length / 2)) : '  ';
+    const newGroup = `${groupIndent}<ItemGroup>${eol}${element}${eol}${groupIndent}</ItemGroup>${eol}`;
+    const closeIdx = text.lastIndexOf('</Project>');
+    if (closeIdx === -1)
+        return `${text}${eol}${newGroup}`;
+    return `${text.slice(0, closeIdx)}${newGroup}${text.slice(closeIdx)}`;
+}
+/** Set the version on an existing element span, honoring whichever form it already uses (attribute, child element, or unversioned). */
+function setElementVersion(element, version) {
+    // Existing Version="x" attribute → replace its value.
+    if (/\bVersion\s*=\s*"[^"]*"/i.test(element)) {
+        return element.replace(/\bVersion\s*=\s*"[^"]*"/i, `Version="${version}"`);
+    }
+    // Existing <Version>x</Version> child element → replace inner text (keep the child form).
+    if (/<Version>[\s\S]*?<\/Version>/i.test(element)) {
+        return element.replace(/<Version>[\s\S]*?<\/Version>/i, `<Version>${version}</Version>`);
+    }
+    // No version present → add a Version attribute to the open tag.
+    if (/\/>\s*$/.test(element)) {
+        // self-close: `<PackageReference Include="id" />` → `... Version="x" />`
+        return element.replace(/\s*\/>\s*$/, ` Version="${version}" />`);
+    }
+    // open/close pair with no child version: add the attribute to the open tag's first `>`.
+    return element.replace(/>/, ` Version="${version}">`);
+}
+/**
+ * Compute the install plan for `descriptor` against `csprojText`. Port of
+ * `ExtensionInstallPlanner.Plan`. Throws {@link CsprojParseError} only on a genuinely
+ * malformed `.csproj` (no recognizable `<Project ...>` root) — the caller maps that to
+ * a structured failure rather than corrupting the file.
+ */
+export function planExtensionInstall(descriptor, csprojText) {
+    if (!/<Project\b[\s\S]*?>/i.test(csprojText) || !/<\/Project>/i.test(csprojText)) {
+        throw new CsprojParseError('The consumer .csproj is not valid XML; refusing to edit it.');
+    }
+    const elementRe = packageRefElementRegex(descriptor.packageId);
+    const match = csprojText.match(elementRe);
+    // --- No existing reference → ADD ---
+    if (!match) {
+        return {
+            action: 'add',
+            resultingCsproj: appendReference(csprojText, descriptor),
+            packageId: descriptor.packageId,
+            fromVersion: null,
+            toVersion: hasVersion(descriptor) ? descriptor.version : null,
+        };
+    }
+    const element = match[0];
+    const currentVersion = readElementVersion(element);
+    // Descriptor pins no version → leave the existing reference untouched.
+    if (!hasVersion(descriptor)) {
+        return {
+            action: 'noop',
+            resultingCsproj: csprojText,
+            packageId: descriptor.packageId,
+            fromVersion: currentVersion,
+            toVersion: null,
+        };
+    }
+    const target = descriptor.version;
+    const needsBump = currentVersion === '' || compareVersions(target, currentVersion) > 0;
+    if (!needsBump) {
+        return {
+            action: 'noop',
+            resultingCsproj: csprojText,
+            packageId: descriptor.packageId,
+            fromVersion: currentVersion,
+            toVersion: target,
+        };
+    }
+    const updatedElement = setElementVersion(element, target);
+    return {
+        action: 'update',
+        // Function replacement so any `$` in the version is never treated as a replacement pattern.
+        resultingCsproj: csprojText.replace(elementRe, () => updatedElement),
+        packageId: descriptor.packageId,
+        fromVersion: currentVersion,
+        toVersion: target,
+    };
+}
+//# sourceMappingURL=extension-install.js.map

package/dist/utils/extension-install.js.map

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

package/dist/utils/extensions-catalog.d.ts

@@ -0,0 +1,35 @@
+/** One tool a catalog extension contributes — mirrors the JSON `tools[]` entry. */
+export interface ExtensionTool {
+    readonly name: string;
+    readonly description: string;
+}
+/**
+ * One installable extension — the CLI analog of the C# `GodotExtensionDescriptor`.
+ * `packageId` is the INSTALL IDENTITY (the `<PackageReference Include="...">`).
+ * `version` is `null` for a floating (unpinned) reference.
+ */
+export interface ExtensionDescriptor {
+    readonly name: string;
+    readonly description: string;
+    readonly packageId: string;
+    readonly version: string | null;
+    readonly gitUrl: string | null;
+    readonly tools: readonly ExtensionTool[];
+}
+/**
+ * The extension catalog, single-sourced from `addons/godot_mcp/extensions.catalog.json`.
+ * Ships EMPTY until the first Godot-MCP extension package is published on nuget.org —
+ * `install-extension <id>` then reports "unknown extension" for every id, which is the
+ * correct behavior (there is nothing to install yet). The parity test keeps this in
+ * lockstep with the JSON so adding an entry there forces an update here.
+ */
+export declare const EXTENSIONS_CATALOG: readonly ExtensionDescriptor[];
+/** True when a descriptor carries a concrete version pin (drives the up-to-date / update decision). */
+export declare function hasVersion(descriptor: ExtensionDescriptor): boolean;
+/**
+ * Resolve a user-supplied `<id>` to a catalog descriptor. Matches by `packageId`
+ * first (ordinal-ignore-case, like NuGet's case-insensitive ids — the install
+ * identity), then falls back to an exact case-insensitive `name` match for
+ * convenience. Returns `null` when absent or `id` is empty.
+ */
+export declare function findExtension(id: string | undefined | null, catalog?: readonly ExtensionDescriptor[]): ExtensionDescriptor | null;

package/dist/utils/extensions-catalog.js

@@ -0,0 +1,46 @@
+// The CLI's typed mirror of the SHARED extension catalog — the single source of
+// truth `addons/godot_mcp/extensions.catalog.json` (see that file's sibling
+// `extensions.catalog.md`). It is the CLI half of the "one catalog consumed by the
+// dock, the CLI, and the app" contract: the dock parses the JSON via an embedded
+// resource (C# `GodotExtensionCatalog`); the CLI mirrors it here so the published
+// npm package stays self-contained (no runtime `../addons` dependency).
+//
+// SINGLE SOURCE OF TRUTH: this constant MUST stay byte-equivalent to the JSON. The
+// parity test `cli/tests/extensions-catalog-parity.test.ts` reads the addon JSON and
+// FAILS the build if this mirror drifts — exactly the discipline `addon-deps.ts` /
+// `addon-deps-parity.test.ts` use for the NuGet pins. Adding an extension =
+// appending an entry to BOTH the JSON and this array (the test enforces it).
+//
+// No top-level side effects; pure data + pure lookups only.
+/**
+ * The extension catalog, single-sourced from `addons/godot_mcp/extensions.catalog.json`.
+ * Ships EMPTY until the first Godot-MCP extension package is published on nuget.org —
+ * `install-extension <id>` then reports "unknown extension" for every id, which is the
+ * correct behavior (there is nothing to install yet). The parity test keeps this in
+ * lockstep with the JSON so adding an entry there forces an update here.
+ */
+export const EXTENSIONS_CATALOG = [
+// (none yet — see addons/godot_mcp/extensions.catalog.json / extensions.catalog.md)
+];
+/** True when a descriptor carries a concrete version pin (drives the up-to-date / update decision). */
+export function hasVersion(descriptor) {
+    return descriptor.version !== null && descriptor.version.trim() !== '';
+}
+/**
+ * Resolve a user-supplied `<id>` to a catalog descriptor. Matches by `packageId`
+ * first (ordinal-ignore-case, like NuGet's case-insensitive ids — the install
+ * identity), then falls back to an exact case-insensitive `name` match for
+ * convenience. Returns `null` when absent or `id` is empty.
+ */
+export function findExtension(id, catalog = EXTENSIONS_CATALOG) {
+    if (id === undefined || id === null)
+        return null;
+    const needle = id.trim();
+    if (needle === '')
+        return null;
+    const byPackageId = catalog.find((d) => d.packageId.toLowerCase() === needle.toLowerCase());
+    if (byPackageId)
+        return byPackageId;
+    return catalog.find((d) => d.name.toLowerCase() === needle.toLowerCase()) ?? null;
+}
+//# sourceMappingURL=extensions-catalog.js.map

package/dist/utils/extensions-catalog.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"extensions-catalog.js","sourceRoot":"","sources":["../../src/utils/extensions-catalog.ts"],"names":[],"mappings":"AAAA,gFAAgF;AAChF,4EAA4E;AAC5E,mFAAmF;AACnF,iFAAiF;AACjF,kFAAkF;AAClF,wEAAwE;AACxE,EAAE;AACF,mFAAmF;AACnF,qFAAqF;AACrF,mFAAmF;AACnF,4EAA4E;AAC5E,6EAA6E;AAC7E,EAAE;AACF,4DAA4D;AAsB5D;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAmC;AAChE,oFAAoF;CAC5E,CAAC;AAEX,uGAAuG;AACvG,MAAM,UAAU,UAAU,CAAC,UAA+B;IACxD,OAAO,UAAU,CAAC,OAAO,KAAK,IAAI,IAAI,UAAU,CAAC,OAAO,CAAC,IAAI,EAAE,KAAK,EAAE,CAAC;AACzE,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,aAAa,CAC3B,EAA6B,EAC7B,UAA0C,kBAAkB;IAE5D,IAAI,EAAE,KAAK,SAAS,IAAI,EAAE,KAAK,IAAI;QAAE,OAAO,IAAI,CAAC;IACjD,MAAM,MAAM,GAAG,EAAE,CAAC,IAAI,EAAE,CAAC;IACzB,IAAI,MAAM,KAAK,EAAE;QAAE,OAAO,IAAI,CAAC;IAE/B,MAAM,WAAW,GAAG,OAAO,CAAC,IAAI,CAC9B,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC,WAAW,EAAE,KAAK,MAAM,CAAC,WAAW,EAAE,CAC1D,CAAC;IACF,IAAI,WAAW;QAAE,OAAO,WAAW,CAAC;IAEpC,OAAO,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,WAAW,EAAE,KAAK,MAAM,CAAC,WAAW,EAAE,CAAC,IAAI,IAAI,CAAC;AACpF,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "godot-cli",
-  "version": "0.13.3",
+  "version": "0.14.0",
   "description": "Cross-platform CLI tool for Godot-MCP (Skills & MCP). Resolves and launches the Godot editor with MCP connection env vars, runs MCP/system tools over HTTP, probes server health, configures AI agents (Claude Code, Cursor, VS Code, …), and enables/disables the godot_mcp addon. Works with Claude Code, Cursor, Copilot, and any MCP client.",
   "type": "module",
   "main": "dist/lib.js",