godot-cli 0.11.1 → 0.12.0

package/README.md

@@ -34,8 +34,8 @@ Requires Node `^20.19.0 || >=22.12.0`.
 | `setup-skills <agent> [path]` | Generate Godot-MCP skill files (a `SKILL.md`-per-tool-family) under the agent's skills path. `--list` shows each agent's skills support. |
 | `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]` | Enable the `godot_mcp` addon in `project.godot` `[editor_plugins]`. |
-| `remove-plugin [path]` | Disable the `godot_mcp` addon in `project.godot` `[editor_plugins]`. |
+| `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. |
+| `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. |
 
 ### Editor resolution (`open`)
@@ -97,6 +97,33 @@ exposes no skill-generate HTTP endpoint, so no server or running editor is requi
 `GodotMcpConnection.Start` → `GenerateSkillFilesIfNeeded`; the CLI command is the
 server-less, scriptable path that does not need a live editor.)
 
+## `install-plugin`
+
+`godot-cli install-plugin [path]` is a **real installer** — it makes a from-scratch terminal install
+produce a working project, in one idempotent command:
+
+```bash
+godot-cli install-plugin ./MyGodotProject                      # download the matching release + install
+godot-cli install-plugin --version 0.11.1 ./MyGodotProject     # pin a specific addon release
+godot-cli install-plugin --source ./Godot-MCP/addons/godot_mcp ./MyGodotProject   # offline / dev copy
+```
+
+It performs three steps:
+
+1. **Materialize `res://addons/godot_mcp/`.** By default it downloads `godot-mcp-addon-<version>.zip`
+   over HTTPS from **github.com only** (the `IvanMurzak/Godot-MCP` release `v<version>`; the version
+   defaults to the CLI's own version). Non-`github.com` hosts and plain `http` are rejected. With
+   `--source <path>` it copies the addon from a local directory instead (no network) — `<path>` may be a
+   directory that *is* `addons/godot_mcp` or one that *contains* it.
+2. **Add the NuGet packages** the addon needs (`com.IvanMurzak.ReflectorNet`, `com.IvanMurzak.McpPlugin`)
+   to the project's `.csproj`, idempotently — adding when missing, reconciling a stale version, and
+   leaving a correct pin untouched. The versions are single-sourced from the addon's own
+   `Godot-MCP.csproj` pins, so the scaffold can never drift.
+3. **Enable the plugin** in `project.godot` `[editor_plugins]`.
+
+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.
+
 ## Library API
 
 The package also exports a side-effect-free library (the `.` entry):

package/dist/commands/install-plugin.js

@@ -1,30 +1,68 @@
 import { Command } from 'commander';
+import { createRequire } from 'module';
 import * as path from 'path';
 import * as ui from '../utils/ui.js';
 import { verbose } from '../utils/ui.js';
 import { installPlugin } from '../lib/install-plugin.js';
+/** The CLI's own version — the default addon release version to download. */
+function cliVersion() {
+    try {
+        const require = createRequire(import.meta.url);
+        const pkg = require('../../package.json');
+        return pkg.version;
+    }
+    catch {
+        return '';
+    }
+}
 export const installPluginCommand = new Command('install-plugin')
-    .description('Enable the godot_mcp addon in a project (adds res://addons/godot_mcp/plugin.cfg to project.godot [editor_plugins])')
+    .description('Install the godot_mcp addon into a Godot C# project: materialize res://addons/godot_mcp/ (download the matching GitHub release, or --source a local copy), add the required NuGet PackageReferences to the project .csproj, and enable the plugin in project.godot.')
     .argument('[path]', 'Path to the Godot project')
     .option('--path <path>', 'Path to the Godot project')
+    .option('--source <path>', 'Install the addon from a local directory (offline / dev / CI) instead of downloading it')
+    .option('--version <x.y.z>', 'Addon release version to download (defaults to this CLI version). Ignored with --source.')
     .action(async (positionalPath, options) => {
     const resolvedPath = positionalPath ?? options.path ?? process.cwd();
     const projectPath = path.resolve(resolvedPath);
-    ui.heading('Enabling godot_mcp addon');
+    ui.heading('Installing godot_mcp addon');
     verbose(`Project path: ${projectPath}`);
-    const spinner = ui.startSpinner('Updating project.godot...');
-    const result = await installPlugin({ godotProjectPath: projectPath });
+    if (options.source)
+        verbose(`--source: ${options.source}`);
+    const spinner = ui.startSpinner('Installing addon...');
+    const result = await installPlugin({
+        godotProjectPath: projectPath,
+        source: options.source,
+        version: options.version ?? cliVersion(),
+    });
     if (result.kind === 'failure') {
-        spinner.error('Failed to enable plugin');
+        spinner.error('Failed to install plugin');
         ui.error(result.error.message);
+        for (const warning of result.warnings) {
+            console.log('');
+            ui.warn(warning);
+        }
         process.exit(1);
     }
     if (result.changed) {
-        spinner.success('godot_mcp addon enabled');
+        spinner.success('godot_mcp addon installed and enabled');
     }
     else {
         spinner.success('godot_mcp addon was already enabled');
     }
+    // Addon files outcome.
+    if (result.materialize.source === 'download') {
+        ui.label('Addon files', `downloaded → ${result.materialize.addonDir}`);
+    }
+    else if (result.materialize.source === 'local') {
+        ui.label('Addon files', `copied from ${result.materialize.sourceDir} → ${result.materialize.addonDir}`);
+    }
+    // csproj outcome.
+    if (result.csproj.csprojPath) {
+        const summary = result.csproj.packages
+            .map((p) => `${p.id}@${p.version} (${p.action})`)
+            .join(', ');
+        ui.label('NuGet packages', summary || '(none)');
+    }
     ui.label('project.godot', result.projectGodotPath);
     ui.label('Enabled plugins', result.enabledPlugins.join(', ') || '(none)');
     for (const warning of result.warnings) {

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

@@ -1 +1 @@
-{"version":3,"file":"install-plugin.js","sourceRoot":"","sources":["../../src/commands/install-plugin.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,KAAK,IAAI,MAAM,MAAM,CAAC;AAC7B,OAAO,KAAK,EAAE,MAAM,gBAAgB,CAAC;AACrC,OAAO,EAAE,OAAO,EAAE,MAAM,gBAAgB,CAAC;AACzC,OAAO,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAC;AAMzD,MAAM,CAAC,MAAM,oBAAoB,GAAG,IAAI,OAAO,CAAC,gBAAgB,CAAC;KAC9D,WAAW,CAAC,oHAAoH,CAAC;KACjI,QAAQ,CAAC,QAAQ,EAAE,2BAA2B,CAAC;KAC/C,MAAM,CAAC,eAAe,EAAE,2BAA2B,CAAC;KACpD,MAAM,CAAC,KAAK,EAAE,cAAkC,EAAE,OAAgC,EAAE,EAAE;IACrF,MAAM,YAAY,GAAG,cAAc,IAAI,OAAO,CAAC,IAAI,IAAI,OAAO,CAAC,GAAG,EAAE,CAAC;IACrE,MAAM,WAAW,GAAG,IAAI,CAAC,OAAO,CAAC,YAAY,CAAC,CAAC;IAE/C,EAAE,CAAC,OAAO,CAAC,0BAA0B,CAAC,CAAC;IACvC,OAAO,CAAC,iBAAiB,WAAW,EAAE,CAAC,CAAC;IAExC,MAAM,OAAO,GAAG,EAAE,CAAC,YAAY,CAAC,2BAA2B,CAAC,CAAC;IAC7D,MAAM,MAAM,GAAG,MAAM,aAAa,CAAC,EAAE,gBAAgB,EAAE,WAAW,EAAE,CAAC,CAAC;IAEtE,IAAI,MAAM,CAAC,IAAI,KAAK,SAAS,EAAE,CAAC;QAC9B,OAAO,CAAC,KAAK,CAAC,yBAAyB,CAAC,CAAC;QACzC,EAAE,CAAC,KAAK,CAAC,MAAM,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;QAC/B,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC;IAED,IAAI,MAAM,CAAC,OAAO,EAAE,CAAC;QACnB,OAAO,CAAC,OAAO,CAAC,yBAAyB,CAAC,CAAC;IAC7C,CAAC;SAAM,CAAC;QACN,OAAO,CAAC,OAAO,CAAC,qCAAqC,CAAC,CAAC;IACzD,CAAC;IAED,EAAE,CAAC,KAAK,CAAC,eAAe,EAAE,MAAM,CAAC,gBAAgB,CAAC,CAAC;IACnD,EAAE,CAAC,KAAK,CAAC,iBAAiB,EAAE,MAAM,CAAC,cAAc,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,QAAQ,CAAC,CAAC;IAE1E,KAAK,MAAM,OAAO,IAAI,MAAM,CAAC,QAAQ,EAAE,CAAC;QACtC,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QAChB,EAAE,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IACnB,CAAC;AACH,CAAC,CAAC,CAAC"}
+{"version":3,"file":"install-plugin.js","sourceRoot":"","sources":["../../src/commands/install-plugin.ts"],"names":[],"mappings":"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"}

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

@@ -1,16 +1,23 @@
 import { projectGodotPath as resolveProjectGodotPath } from '../utils/project-godot.js';
 import type { InstallPluginOptions, InstallPluginResult, RemovePluginOptions, RemovePluginResult } from './types.js';
 /**
- * Enable the `godot_mcp` addon in a project's `project.godot` `[editor_plugins]`
- * `enabled` array. Library-safe: no stdout noise, no process.exit, no throws
- * past the public boundary.
+ * Install the `godot_mcp` addon into a Godot C# project as a REAL installer:
  *
- * v1 is intentionally minimal — it only flips the project.godot plugin-enable
- * state. It does NOT copy addon files or patch the consumer `.csproj` with the
- * NuGet PackageReferences the addon needs (that is the consumer's responsibility
- * per the addon's install docs); a warning surfaces that requirement.
+ *  1. Materialize `res://addons/godot_mcp/` — by default downloading
+ *     `godot-mcp-addon-<version>.zip` over HTTPS from github.com only (the
+ *     `IvanMurzak/Godot-MCP` release `v<version>`), or, with `--source <path>`,
+ *     copying the addon from a local directory (offline / dev / CI).
+ *  2. Add the two NuGet `PackageReference`s the addon needs to the consumer
+ *     `.csproj`, idempotently and single-sourced from the addon's own pins.
+ *  3. Flip the `[editor_plugins] enabled` flag in `project.godot`.
  *
- * Idempotent: enabling an already-enabled plugin returns `changed: false`.
+ * 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 addon present, the pins present, and the plugin already
+ * enabled reports `changed: false` and makes no writes. On a download/copy
+ * failure the project is left as found: both paths materialize into a temp
+ * sibling and only swap it into the addon dir after a fully successful
+ * fetch+extract / copy, so a partial materialization is rolled back.
  */
 export declare function installPlugin(opts: InstallPluginOptions): Promise<InstallPluginResult>;
 /**

package/dist/lib/install-plugin.js

@@ -1,18 +1,32 @@
 import * as fs from 'fs';
+import * as path from 'path';
 import { GODOT_MCP_PLUGIN_PATH, projectGodotPath as resolveProjectGodotPath, togglePluginInText, } from '../utils/project-godot.js';
+import { addAddonPackageReferences } from '../utils/csproj-deps.js';
+import { ADDON_PACKAGE_REFERENCES } from '../utils/addon-deps.js';
+import { addonDownloadUrl, assertTrustedDownloadUrl, } from '../utils/addon-source.js';
+import { parseZip } from '../utils/unzip.js';
 import { emitProgress } from './progress.js';
 import { requireGodotProject } from './validation.js';
+/** Relative path of the addon dir inside a Godot project. */
+const ADDON_REL_DIR = path.join('addons', 'godot_mcp');
 /**
- * Enable the `godot_mcp` addon in a project's `project.godot` `[editor_plugins]`
- * `enabled` array. Library-safe: no stdout noise, no process.exit, no throws
- * past the public boundary.
+ * Install the `godot_mcp` addon into a Godot C# project as a REAL installer:
  *
- * v1 is intentionally minimal — it only flips the project.godot plugin-enable
- * state. It does NOT copy addon files or patch the consumer `.csproj` with the
- * NuGet PackageReferences the addon needs (that is the consumer's responsibility
- * per the addon's install docs); a warning surfaces that requirement.
+ *  1. Materialize `res://addons/godot_mcp/` — by default downloading
+ *     `godot-mcp-addon-<version>.zip` over HTTPS from github.com only (the
+ *     `IvanMurzak/Godot-MCP` release `v<version>`), or, with `--source <path>`,
+ *     copying the addon from a local directory (offline / dev / CI).
+ *  2. Add the two NuGet `PackageReference`s the addon needs to the consumer
+ *     `.csproj`, idempotently and single-sourced from the addon's own pins.
+ *  3. Flip the `[editor_plugins] enabled` flag in `project.godot`.
  *
- * Idempotent: enabling an already-enabled plugin returns `changed: false`.
+ * 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 addon present, the pins present, and the plugin already
+ * enabled reports `changed: false` and makes no writes. On a download/copy
+ * failure the project is left as found: both paths materialize into a temp
+ * sibling and only swap it into the addon dir after a fully successful
+ * fetch+extract / copy, so a partial materialization is rolled back.
  */
 export async function installPlugin(opts) {
     const warnings = [];
@@ -30,26 +44,32 @@ export async function installPlugin(opts) {
         const { projectPath, projectGodotPath } = validated;
         emitProgress(opts.onProgress, {
             phase: 'start',
-            message: `Enabling godot_mcp addon for ${projectPath}`,
+            message: `Installing godot_mcp addon into ${projectPath}`,
         });
+        // 1. Materialize the addon files (download / local copy / skip).
+        const materialize = await materializeAddon(projectPath, opts, warnings);
+        // 2. Patch the consumer csproj with the addon's NuGet PackageReferences.
+        const csproj = patchConsumerCsproj(projectPath, warnings, opts.onProgress);
+        // 3. Enable the plugin in project.godot.
         const text = fs.readFileSync(projectGodotPath, 'utf-8');
-        const result = togglePluginInText(text, true, GODOT_MCP_PLUGIN_PATH);
-        if (result.kind === 'changed') {
-            fs.writeFileSync(projectGodotPath, result.text);
+        const toggled = togglePluginInText(text, true, GODOT_MCP_PLUGIN_PATH);
+        if (toggled.kind === 'changed') {
+            fs.writeFileSync(projectGodotPath, toggled.text);
             emitProgress(opts.onProgress, {
                 phase: 'manifest-patched',
                 message: `Wrote ${projectGodotPath}`,
                 manifestPath: projectGodotPath,
             });
         }
-        warnings.push('Ensure the project .csproj declares the com.IvanMurzak.ReflectorNet and com.IvanMurzak.McpPlugin PackageReferences the addon needs (see the addon README).');
-        emitProgress(opts.onProgress, { phase: 'done', message: 'godot_mcp addon enabled.' });
+        emitProgress(opts.onProgress, { phase: 'done', message: 'godot_mcp addon installed.' });
         return {
             kind: 'success',
             success: true,
-            changed: result.kind === 'changed',
+            changed: toggled.kind === 'changed',
             projectGodotPath,
-            enabledPlugins: result.enabled,
+            enabledPlugins: toggled.enabled,
+            materialize,
+            csproj,
             warnings,
         };
     }
@@ -62,6 +82,208 @@ export async function installPlugin(opts) {
         };
     }
 }
+/**
+ * Materialize `addons/godot_mcp/` into the project from the GitHub release zip
+ * (default) or a local `--source` directory. Idempotent for the local-copy and
+ * download paths: the target dir is replaced atomically-ish (extract/copy into a
+ * temp sibling, then swap), so a failure leaves the existing addon untouched.
+ */
+async function materializeAddon(projectPath, opts, warnings) {
+    const addonDir = path.join(projectPath, ADDON_REL_DIR);
+    if (opts.skipMaterialize === true) {
+        if (!fs.existsSync(path.join(addonDir, 'plugin.cfg'))) {
+            warnings.push(`skipMaterialize was set but ${path.join(addonDir, 'plugin.cfg')} is absent — the editor cannot load the plugin until the addon files are present.`);
+        }
+        return { source: 'skipped', addonDir };
+    }
+    if (opts.source !== undefined && opts.source !== '') {
+        const sourceDir = resolveAddonSourceDir(opts.source);
+        copyAddonFromLocal(sourceDir, projectPath, addonDir, opts.onProgress);
+        emitProgress(opts.onProgress, {
+            phase: 'addon-materialized',
+            message: `Copied addon from ${sourceDir}`,
+            addonDir,
+            source: 'local',
+        });
+        return { source: 'local', addonDir, sourceDir };
+    }
+    // Download path. Default the version to the CLI's own version (passed by the
+    // command via opts.version); fail clearly if neither is available.
+    const version = (opts.version ?? '').trim();
+    if (version === '') {
+        throw new Error('No addon version to download. Pass --version <x.y.z> or --source <path> to install from a local copy.');
+    }
+    const url = addonDownloadUrl(version);
+    assertTrustedDownloadUrl(url); // fail-closed: github.com + https only.
+    emitProgress(opts.onProgress, {
+        phase: 'addon-downloading',
+        message: `Downloading addon ${version} from ${url}`,
+        url,
+    });
+    const fetchImpl = opts.fetchImpl ?? globalThis.fetch;
+    const response = await fetchImpl(url);
+    if (!response.ok) {
+        throw new Error(`Failed to download addon ${version}: HTTP ${response.status} ${response.statusText} from ${url}. ` +
+            `Verify the release v${version} exists, or use --source <path> for an offline/dev install.`);
+    }
+    const archive = Buffer.from(await response.arrayBuffer());
+    emitProgress(opts.onProgress, { phase: 'addon-extracting', message: 'Extracting addon zip' });
+    const entries = parseZip(archive);
+    extractAddonEntries(entries, projectPath, addonDir);
+    emitProgress(opts.onProgress, {
+        phase: 'addon-materialized',
+        message: `Downloaded + extracted addon to ${addonDir}`,
+        addonDir,
+        source: 'download',
+    });
+    return { source: 'download', addonDir, downloadUrl: url };
+}
+/** Resolve + validate a `--source` directory: it must exist and contain plugin.cfg. */
+function resolveAddonSourceDir(source) {
+    const resolved = path.resolve(source);
+    // Accept either a path that IS addons/godot_mcp (contains plugin.cfg directly)
+    // or a path that CONTAINS addons/godot_mcp.
+    if (fs.existsSync(path.join(resolved, 'plugin.cfg'))) {
+        return resolved;
+    }
+    const nested = path.join(resolved, 'addons', 'godot_mcp');
+    if (fs.existsSync(path.join(nested, 'plugin.cfg'))) {
+        return nested;
+    }
+    throw new Error(`--source ${resolved} does not contain a godot_mcp addon (no plugin.cfg found at it or at addons/godot_mcp/).`);
+}
+/**
+ * Materialize the addon into a fresh staging sibling via `fill`, then atomically
+ * swap it into `addonDir`. A mid-fill failure leaves the existing addon untouched
+ * (staging is discarded), honoring the install's documented rollback guarantee.
+ * Shared by both the local-copy and download/extract paths.
+ */
+function stageThenSwapAddon(projectPath, addonDir, fill) {
+    const addonReal = path.resolve(addonDir);
+    const staging = path.resolve(projectPath, `.godot-mcp-addon-staging-${process.pid}-${Date.now()}`);
+    fs.rmSync(staging, { recursive: true, force: true });
+    fs.mkdirSync(staging, { recursive: true });
+    try {
+        fill(staging);
+        // Swap staging -> addonDir only after `fill` fully succeeded.
+        fs.rmSync(addonReal, { recursive: true, force: true });
+        fs.mkdirSync(path.dirname(addonReal), { recursive: true });
+        fs.renameSync(staging, addonReal);
+    }
+    finally {
+        // Best-effort cleanup if the swap didn't consume staging.
+        fs.rmSync(staging, { recursive: true, force: true });
+    }
+}
+/**
+ * Recursively copy a local addon dir into the project's addons/godot_mcp/. Stages
+ * into a temp sibling and swaps, so a mid-copy failure leaves the existing addon
+ * intact (matching the download path's rollback guarantee). Deterministic +
+ * idempotent: the swap replaces any existing addon dir.
+ */
+function copyAddonFromLocal(sourceDir, projectPath, addonDir, onProgress) {
+    emitProgress(onProgress, { phase: 'addon-extracting', message: `Copying addon from ${sourceDir}` });
+    stageThenSwapAddon(projectPath, addonDir, (staging) => {
+        fs.cpSync(sourceDir, staging, { recursive: true });
+        if (!fs.existsSync(path.join(staging, 'plugin.cfg'))) {
+            throw new Error(`Copy completed but ${path.join(sourceDir, 'plugin.cfg')} did not yield a plugin.cfg.`);
+        }
+    });
+}
+/**
+ * Write the zip entries that live under `addons/godot_mcp/` into the project. The
+ * release zip expands to `addons/godot_mcp/...`, so entries are written relative
+ * to the project root. Path-safety: every resolved target MUST stay inside the
+ * staging dir (reject zip-slip `../` traversal). The target addon dir is replaced
+ * atomically so the install is deterministic + idempotent and rollback-safe.
+ */
+function extractAddonEntries(entries, projectPath, addonDir) {
+    stageThenSwapAddon(projectPath, addonDir, (staging) => {
+        let wrotePluginCfg = false;
+        for (const entry of entries) {
+            // Only the addons/godot_mcp/ subtree is relevant.
+            const prefix = 'addons/godot_mcp/';
+            if (!entry.path.startsWith(prefix))
+                continue;
+            const rel = entry.path.slice(prefix.length);
+            if (rel === '')
+                continue; // the dir entry itself
+            const target = path.resolve(staging, rel);
+            // Zip-slip guard: target must remain under staging.
+            if (target !== staging && !target.startsWith(staging + path.sep)) {
+                throw new Error(`Refusing to extract entry escaping the addon dir: ${entry.path}`);
+            }
+            if (entry.isDirectory) {
+                fs.mkdirSync(target, { recursive: true });
+                continue;
+            }
+            fs.mkdirSync(path.dirname(target), { recursive: true });
+            fs.writeFileSync(target, entry.bytes);
+            if (rel === 'plugin.cfg')
+                wrotePluginCfg = true;
+        }
+        if (!wrotePluginCfg) {
+            throw new Error('Downloaded addon zip did not contain addons/godot_mcp/plugin.cfg — the archive is not a valid godot_mcp addon release.');
+        }
+    });
+}
+/**
+ * Find the consumer's `.csproj` (the one Godot compiles the addon into) and add
+ * the two addon NuGet PackageReferences idempotently. The csproj is the single
+ * `*.csproj` at the project root (the `--dotnet` scaffold writes
+ * `<AssemblyName>.csproj` there). When there is no csproj (a GDScript-only
+ * project), the patch is skipped with a warning — the addon's C# cannot compile
+ * without one, but that is the consumer's project shape to fix.
+ */
+function patchConsumerCsproj(projectPath, warnings, onProgress) {
+    const csprojPath = findConsumerCsproj(projectPath, warnings);
+    if (csprojPath === null) {
+        warnings.push('No .csproj found at the project root — the godot_mcp addon is C# and needs a Godot.NET.Sdk project. ' +
+            `Create one (e.g. \`godot-cli create-project --dotnet\`) and add the ${ADDON_PACKAGE_REFERENCES.map((r) => r.id).join(' + ')} PackageReferences.`);
+        return { changed: false, packages: [] };
+    }
+    const before = fs.readFileSync(csprojPath, 'utf-8');
+    const patched = addAddonPackageReferences(before);
+    if (patched.changed) {
+        fs.writeFileSync(csprojPath, patched.text);
+        emitProgress(onProgress, {
+            phase: 'csproj-patched',
+            message: `Added addon PackageReferences to ${csprojPath}`,
+            csprojPath,
+        });
+    }
+    return {
+        csprojPath,
+        changed: patched.changed,
+        packages: patched.changes.map((c) => ({
+            id: c.id,
+            action: c.action,
+            version: c.version,
+        })),
+    };
+}
+/** The single `*.csproj` directly at the project root, or null when none/ambiguous. */
+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;
+    // A scaffolded Godot project has exactly one root csproj. If there are several,
+    // pick deterministically (first alphabetically) — better than failing the whole
+    // install; all root csprojs compile into the same Godot assembly and would each
+    // need the pins, but warn so the heuristic's choice is observable.
+    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 addon PackageReferences to it as well.');
+    }
+    return path.join(projectPath, names[0]);
+}
 /**
  * Disable the `godot_mcp` addon in a project's `project.godot`
  * `[editor_plugins]` `enabled` array. Idempotent: disabling an already-absent

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

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

package/dist/lib/types.d.ts

@@ -9,6 +9,22 @@ export type ProgressEvent = {
     phase: 'manifest-patched';
     message: string;
     manifestPath: string;
+} | {
+    phase: 'addon-downloading';
+    message: string;
+    url: string;
+} | {
+    phase: 'addon-extracting';
+    message: string;
+} | {
+    phase: 'addon-materialized';
+    message: string;
+    addonDir: string;
+    source: 'download' | 'local';
+} | {
+    phase: 'csproj-patched';
+    message: string;
+    csprojPath: string;
 } | {
     phase: 'project-scaffolded';
     message: string;
@@ -237,8 +253,55 @@ export type RunSystemToolFailure = RunToolFailure;
 export interface InstallPluginOptions {
     /** Absolute or relative path to the Godot project root. */
     godotProjectPath: string;
+    /**
+     * Local directory to copy `addons/godot_mcp/` from instead of downloading it
+     * from the GitHub release (offline / dev / CI path). When set, no network call
+     * is made; the directory must contain the addon files (a `plugin.cfg`).
+     */
+    source?: string;
+    /**
+     * Addon release version to download (`<version>` in
+     * `godot-mcp-addon-<version>.zip`, tag `v<version>`). Defaults to the CLI's own
+     * version. Ignored when `source` is set. Used only on the download path.
+     */
+    version?: string;
+    /**
+     * Skip materializing the addon files (download / copy) and only enable the
+     * plugin + patch the csproj. Restores the pre-installer behavior for callers
+     * that manage the addon files themselves.
+     */
+    skipMaterialize?: boolean;
+    /**
+     * Injectable fetch for tests (mock the GitHub download). Defaults to
+     * `globalThis.fetch`. Used only on the download path.
+     */
+    fetchImpl?: typeof fetch;
     onProgress?: ProgressCallback;
 }
+/** What `install-plugin` did to materialize the `addons/godot_mcp/` files. */
+export interface AddonMaterializeOutcome {
+    /** Where the addon files came from. `skipped` when `skipMaterialize` was set. */
+    source: 'download' | 'local' | 'skipped';
+    /** Absolute path to the materialized `addons/godot_mcp/` directory. */
+    addonDir: string;
+    /** The download URL used (download path only). */
+    downloadUrl?: string;
+    /** The local source directory used (`--source` path only). */
+    sourceDir?: string;
+}
+/** What `install-plugin` did to the consumer `.csproj`'s PackageReferences. */
+export interface CsprojPatchOutcome {
+    /** Absolute path to the consumer `.csproj` that was patched, if one was found. */
+    csprojPath?: string;
+    /** True when the csproj text was modified. */
+    changed: boolean;
+    /** Per-package summary: each addon pin's add / update / unchanged outcome. */
+    packages: {
+        id: string;
+        action: 'added' | 'updated' | 'unchanged';
+        version: string;
+    }[];
+}
 export interface InstallPluginSuccess {
     kind: 'success';
     success: true;
@@ -246,6 +309,10 @@ export interface InstallPluginSuccess {
     changed: boolean;
     projectGodotPath: string;
     enabledPlugins: string[];
+    /** Addon-files materialization outcome (download / local copy / skipped). */
+    materialize: AddonMaterializeOutcome;
+    /** Consumer csproj PackageReference patch outcome. */
+    csproj: CsprojPatchOutcome;
     warnings: string[];
 }
 export interface InstallPluginFailure {

package/dist/lib.d.ts

@@ -4,4 +4,4 @@ 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, 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, RemovePluginOptions, RemovePluginResult, RemovePluginSuccess, RemovePluginFailure, } from './lib/types.js';
+export type { ProgressEvent, ProgressCallback, ResultKind, OpenProjectOptions, OpenProjectResult, OpenProjectSuccess, OpenProjectFailure, OpenProjectAuthOption, OpenProjectConnectionMode, 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';

package/dist/utils/addon-deps.d.ts

@@ -0,0 +1,15 @@
+/** A single NuGet `<PackageReference>` the consumer csproj must declare. */
+export interface AddonPackageReference {
+    /** The NuGet package id (the `Include=` attribute). */
+    id: string;
+    /** The pinned version (the `Version=` attribute). */
+    version: string;
+}
+/**
+ * The exact NuGet `PackageReference`s the consumer's project `.csproj` needs,
+ * single-sourced from the addon's `Godot-MCP.csproj` pins. Order matches the
+ * addon csproj (ReflectorNet first, then McpPlugin).
+ */
+export declare const ADDON_PACKAGE_REFERENCES: readonly AddonPackageReference[];
+/** The resource path of the addon manifest a consumer project loads the plugin from. */
+export declare const ADDON_PLUGIN_CFG_RESOURCE = "res://addons/godot_mcp/plugin.cfg";

package/dist/utils/addon-deps.js

@@ -0,0 +1,27 @@
+// The NuGet PackageReferences a consumer's Godot C# project MUST declare so the
+// `addons/godot_mcp/` sources compile into the project assembly (Godot globs every
+// `*.cs` under the project into one assembly — see the addon README
+// "Consumer-install story"). `install-plugin` writes these into the generated
+// consumer `.csproj` so a from-scratch terminal install actually builds.
+//
+// SINGLE SOURCE OF TRUTH: these values mirror the addon's own reused pins in
+// `Godot-MCP.csproj` (`com.IvanMurzak.ReflectorNet`, `com.IvanMurzak.McpPlugin`).
+// They are NOT a bump of those pins — they are the SAME values, copied so the
+// scaffold installs exactly what the addon was built against. A parity test
+// (`cli/tests/addon-deps-parity.test.ts`) reads `Godot-MCP.csproj` and FAILS the
+// build if these constants ever drift from the addon's pins, so the scaffold can
+// never silently install a mismatched version.
+//
+// No top-level side effects; pure data + pure string transforms only.
+/**
+ * The exact NuGet `PackageReference`s the consumer's project `.csproj` needs,
+ * single-sourced from the addon's `Godot-MCP.csproj` pins. Order matches the
+ * addon csproj (ReflectorNet first, then McpPlugin).
+ */
+export const ADDON_PACKAGE_REFERENCES = [
+    { id: 'com.IvanMurzak.ReflectorNet', version: '5.3.1' },
+    { id: 'com.IvanMurzak.McpPlugin', version: '6.10.0' },
+];
+/** The resource path of the addon manifest a consumer project loads the plugin from. */
+export const ADDON_PLUGIN_CFG_RESOURCE = 'res://addons/godot_mcp/plugin.cfg';
+//# sourceMappingURL=addon-deps.js.map

package/dist/utils/addon-deps.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"addon-deps.js","sourceRoot":"","sources":["../../src/utils/addon-deps.ts"],"names":[],"mappings":"AAAA,gFAAgF;AAChF,mFAAmF;AACnF,oEAAoE;AACpE,8EAA8E;AAC9E,yEAAyE;AACzE,EAAE;AACF,6EAA6E;AAC7E,kFAAkF;AAClF,8EAA8E;AAC9E,4EAA4E;AAC5E,iFAAiF;AACjF,iFAAiF;AACjF,+CAA+C;AAC/C,EAAE;AACF,sEAAsE;AAUtE;;;;GAIG;AACH,MAAM,CAAC,MAAM,wBAAwB,GAAqC;IACxE,EAAE,EAAE,EAAE,6BAA6B,EAAE,OAAO,EAAE,OAAO,EAAE;IACvD,EAAE,EAAE,EAAE,0BAA0B,EAAE,OAAO,EAAE,QAAQ,EAAE;CAC7C,CAAC;AAEX,wFAAwF;AACxF,MAAM,CAAC,MAAM,yBAAyB,GAAG,mCAAmC,CAAC"}

package/dist/utils/addon-source.d.ts

@@ -0,0 +1,36 @@
+/** GitHub-release host the addon zip is downloaded from. NOTHING else is trusted. */
+export declare const TRUSTED_DOWNLOAD_HOST = "github.com";
+/** The `owner/repo` the addon releases live under. */
+export declare const ADDON_RELEASE_REPO = "IvanMurzak/Godot-MCP";
+/**
+ * The release-asset name for an addon version: `godot-mcp-addon-<version>.zip`.
+ * Matches the asset the release workflow attaches (`release.yml` → "Package addon
+ * zip": `zip_name="godot-mcp-addon-${version}.zip"`). The `<version>` is the bare
+ * version WITHOUT a leading `v` (the `v` only appears in the tag). Pure.
+ */
+export declare function addonAssetName(version: string): string;
+/**
+ * The git release TAG for an addon version: the version with a leading `v`
+ * (`0.11.1` → `v0.11.1`). The release workflow tags every release `v<version>`
+ * (`release.yml` → `tag=v${version}`); an already-`v`-prefixed input is passed
+ * through unchanged so a caller cannot double-prefix. Pure.
+ */
+export declare function releaseTag(version: string): string;
+/** Drop a single leading `v`/`V` from a version string. Pure. */
+export declare function stripLeadingV(version: string): string;
+/**
+ * The download URL for an addon version's zip:
+ * `https://github.com/IvanMurzak/Godot-MCP/releases/download/v<version>/godot-mcp-addon-<version>.zip`.
+ * Mirrors `GodotMcpServerView.DownloadUrl`. Pure string build. The host is always
+ * `github.com` by construction; `assertTrustedDownloadUrl` re-checks a
+ * caller-supplied URL before any network call.
+ */
+export declare function addonDownloadUrl(version: string): string;
+/**
+ * Fail-closed host trust check: throw unless `url` is an HTTPS URL whose host is
+ * EXACTLY `github.com` (no subdomains, no `github.com.evil.test`, no http). This
+ * is the security boundary the task requires — reject non-github hosts. Returns
+ * the parsed URL on success. Pure (throws on the unhappy path; the caller turns
+ * it into a structured failure so nothing escapes the public boundary).
+ */
+export declare function assertTrustedDownloadUrl(url: string): URL;

package/dist/utils/addon-source.js

@@ -0,0 +1,68 @@
+// Pure helpers for resolving WHERE the `addons/godot_mcp/` files come from when
+// `install-plugin` materializes them: the trusted GitHub-release download URL and
+// the host-trust check. Mirrors the addon's own trusted-source pattern in
+// `addons/godot_mcp/Runtime/Connection/GodotMcpServerView.cs` (github.com only,
+// `releases/download/v<version>/<asset>`). No side effects; unit-testable.
+/** GitHub-release host the addon zip is downloaded from. NOTHING else is trusted. */
+export const TRUSTED_DOWNLOAD_HOST = 'github.com';
+/** The `owner/repo` the addon releases live under. */
+export const ADDON_RELEASE_REPO = 'IvanMurzak/Godot-MCP';
+/**
+ * The release-asset name for an addon version: `godot-mcp-addon-<version>.zip`.
+ * Matches the asset the release workflow attaches (`release.yml` → "Package addon
+ * zip": `zip_name="godot-mcp-addon-${version}.zip"`). The `<version>` is the bare
+ * version WITHOUT a leading `v` (the `v` only appears in the tag). Pure.
+ */
+export function addonAssetName(version) {
+    return `godot-mcp-addon-${stripLeadingV(version)}.zip`;
+}
+/**
+ * The git release TAG for an addon version: the version with a leading `v`
+ * (`0.11.1` → `v0.11.1`). The release workflow tags every release `v<version>`
+ * (`release.yml` → `tag=v${version}`); an already-`v`-prefixed input is passed
+ * through unchanged so a caller cannot double-prefix. Pure.
+ */
+export function releaseTag(version) {
+    const v = (version ?? '').trim();
+    return v.startsWith('v') ? v : `v${v}`;
+}
+/** Drop a single leading `v`/`V` from a version string. Pure. */
+export function stripLeadingV(version) {
+    const v = (version ?? '').trim();
+    return /^v/i.test(v) ? v.slice(1) : v;
+}
+/**
+ * The download URL for an addon version's zip:
+ * `https://github.com/IvanMurzak/Godot-MCP/releases/download/v<version>/godot-mcp-addon-<version>.zip`.
+ * Mirrors `GodotMcpServerView.DownloadUrl`. Pure string build. The host is always
+ * `github.com` by construction; `assertTrustedDownloadUrl` re-checks a
+ * caller-supplied URL before any network call.
+ */
+export function addonDownloadUrl(version) {
+    const bare = stripLeadingV(version);
+    return `https://${TRUSTED_DOWNLOAD_HOST}/${ADDON_RELEASE_REPO}/releases/download/${releaseTag(version)}/${addonAssetName(bare)}`;
+}
+/**
+ * Fail-closed host trust check: throw unless `url` is an HTTPS URL whose host is
+ * EXACTLY `github.com` (no subdomains, no `github.com.evil.test`, no http). This
+ * is the security boundary the task requires — reject non-github hosts. Returns
+ * the parsed URL on success. Pure (throws on the unhappy path; the caller turns
+ * it into a structured failure so nothing escapes the public boundary).
+ */
+export function assertTrustedDownloadUrl(url) {
+    let parsed;
+    try {
+        parsed = new URL(url);
+    }
+    catch {
+        throw new Error(`Refusing to download addon: malformed URL "${url}".`);
+    }
+    if (parsed.protocol !== 'https:') {
+        throw new Error(`Refusing to download addon: only https is allowed, got "${parsed.protocol}" (${url}).`);
+    }
+    if (parsed.hostname.toLowerCase() !== TRUSTED_DOWNLOAD_HOST) {
+        throw new Error(`Refusing to download addon from untrusted host "${parsed.hostname}". Only ${TRUSTED_DOWNLOAD_HOST} is trusted.`);
+    }
+    return parsed;
+}
+//# sourceMappingURL=addon-source.js.map

package/dist/utils/addon-source.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"addon-source.js","sourceRoot":"","sources":["../../src/utils/addon-source.ts"],"names":[],"mappings":"AAAA,gFAAgF;AAChF,kFAAkF;AAClF,0EAA0E;AAC1E,gFAAgF;AAChF,2EAA2E;AAE3E,qFAAqF;AACrF,MAAM,CAAC,MAAM,qBAAqB,GAAG,YAAY,CAAC;AAElD,sDAAsD;AACtD,MAAM,CAAC,MAAM,kBAAkB,GAAG,sBAAsB,CAAC;AAEzD;;;;;GAKG;AACH,MAAM,UAAU,cAAc,CAAC,OAAe;IAC5C,OAAO,mBAAmB,aAAa,CAAC,OAAO,CAAC,MAAM,CAAC;AACzD,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,UAAU,CAAC,OAAe;IACxC,MAAM,CAAC,GAAG,CAAC,OAAO,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;IACjC,OAAO,CAAC,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC;AACzC,CAAC;AAED,iEAAiE;AACjE,MAAM,UAAU,aAAa,CAAC,OAAe;IAC3C,MAAM,CAAC,GAAG,CAAC,OAAO,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;IACjC,OAAO,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;AACxC,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,gBAAgB,CAAC,OAAe;IAC9C,MAAM,IAAI,GAAG,aAAa,CAAC,OAAO,CAAC,CAAC;IACpC,OAAO,WAAW,qBAAqB,IAAI,kBAAkB,sBAAsB,UAAU,CAAC,OAAO,CAAC,IAAI,cAAc,CAAC,IAAI,CAAC,EAAE,CAAC;AACnI,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,wBAAwB,CAAC,GAAW;IAClD,IAAI,MAAW,CAAC;IAChB,IAAI,CAAC;QACH,MAAM,GAAG,IAAI,GAAG,CAAC,GAAG,CAAC,CAAC;IACxB,CAAC;IAAC,MAAM,CAAC;QACP,MAAM,IAAI,KAAK,CAAC,8CAA8C,GAAG,IAAI,CAAC,CAAC;IACzE,CAAC;IACD,IAAI,MAAM,CAAC,QAAQ,KAAK,QAAQ,EAAE,CAAC;QACjC,MAAM,IAAI,KAAK,CACb,2DAA2D,MAAM,CAAC,QAAQ,MAAM,GAAG,IAAI,CACxF,CAAC;IACJ,CAAC;IACD,IAAI,MAAM,CAAC,QAAQ,CAAC,WAAW,EAAE,KAAK,qBAAqB,EAAE,CAAC;QAC5D,MAAM,IAAI,KAAK,CACb,mDAAmD,MAAM,CAAC,QAAQ,WAAW,qBAAqB,cAAc,CACjH,CAAC;IACJ,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/dist/utils/csproj-deps.d.ts

@@ -0,0 +1,40 @@
+import { type AddonPackageReference } from './addon-deps.js';
+/**
+ * Idempotently reconcile a Godot consumer `.csproj`'s `<PackageReference>`s so it
+ * declares exactly the addon's two required NuGet pins (see `addon-deps.ts`).
+ *
+ * Pure: operates on the csproj TEXT and returns the new text + what changed; never
+ * touches the filesystem. Exported for unit tests. Handles, idempotently:
+ *  - a project with NO `<ItemGroup>` at all (appends one before `</Project>`);
+ *  - a project that already declares both pins at the right version (no change);
+ *  - a project that declares one or both at a DIFFERENT version (reconciles in place);
+ *  - a project that declares only one of the two (adds the missing one).
+ *
+ * It deliberately does a minimal, well-scoped text edit rather than a full XML
+ * parse/serialize, to preserve the rest of the consumer's csproj formatting
+ * verbatim. The `<PackageReference Include="..." />` shape it reads/writes is the
+ * single self-closing form the scaffold and the addon README both use.
+ */
+export type CsprojPatchChange = {
+    id: string;
+    action: 'added';
+    version: string;
+} | {
+    id: string;
+    action: 'updated';
+    from: string;
+    version: string;
+} | {
+    id: string;
+    action: 'unchanged';
+    version: string;
+};
+export interface CsprojPatchResult {
+    /** The new csproj text (identical to input when nothing changed). */
+    text: string;
+    /** True when the text was modified. */
+    changed: boolean;
+    /** One entry per required package describing what happened to it. */
+    changes: CsprojPatchChange[];
+}
+export declare function addAddonPackageReferences(csprojText: string, requiredRefs?: readonly AddonPackageReference[]): CsprojPatchResult;

package/dist/utils/csproj-deps.js

@@ -0,0 +1,121 @@
+import { ADDON_PACKAGE_REFERENCES } from './addon-deps.js';
+/** Escape a string for use inside a RegExp source. */
+function escapeRegExp(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+/**
+ * Match an existing `<PackageReference Include="<id>" Version="<ver>" />` element
+ * for a specific package id, capturing the whole element and its version, in
+ * either attribute order (`Include` before or after `Version`). The element may
+ * also be a `<PackageReference ...></PackageReference>` open/close pair.
+ */
+function packageRefRegex(id) {
+    const escId = escapeRegExp(id);
+    // <PackageReference ... Include="id" ... Version="x" ... /> (Include before Version)
+    // or Version before Include. Two alternations cover both orders; either may end
+    // with a self-close `/>` or an explicit `></PackageReference>`.
+    return new RegExp(`<PackageReference\\b[^>]*?\\bInclude\\s*=\\s*"${escId}"[^>]*?\\bVersion\\s*=\\s*"([^"]*)"[^>]*?(?:/>|></PackageReference>)` +
+        `|` +
+        `<PackageReference\\b[^>]*?\\bVersion\\s*=\\s*"([^"]*)"[^>]*?\\bInclude\\s*=\\s*"${escId}"[^>]*?(?:/>|></PackageReference>)`, 'i');
+}
+/** Render the canonical self-closing element for a required reference. */
+function renderRef(ref) {
+    return `<PackageReference Include="${ref.id}" Version="${ref.version}" />`;
+}
+/**
+ * Detect the indentation used by the FIRST existing `<PackageReference>` (or fall
+ * back to 4 spaces) so appended/inserted elements match the consumer's style.
+ */
+function detectIndent(text) {
+    const m = text.match(/\n([ \t]*)<PackageReference\b/);
+    return m ? m[1] : '    ';
+}
+/**
+ * Detect the dominant line ending of the csproj so inserted/appended XML matches
+ * it (a CRLF csproj should not gain bare-LF lines). Returns `\r\n` when CRLF
+ * line endings outnumber bare-LF ones, else `\n`.
+ */
+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';
+}
+export function addAddonPackageReferences(csprojText, requiredRefs = ADDON_PACKAGE_REFERENCES) {
+    const changes = [];
+    let text = csprojText;
+    const indent = detectIndent(text);
+    const eol = detectEol(text);
+    // First pass: reconcile any references that already exist (possibly at a
+    // different version). Collect the ones still missing for the append pass.
+    const missing = [];
+    for (const ref of requiredRefs) {
+        const re = packageRefRegex(ref.id);
+        const match = text.match(re);
+        if (!match) {
+            missing.push(ref);
+            continue;
+        }
+        const existingVersion = match[1] ?? match[2] ?? '';
+        if (existingVersion === ref.version) {
+            changes.push({ id: ref.id, action: 'unchanged', version: ref.version });
+            continue;
+        }
+        // Reconcile in place: replace the whole element with the canonical pin.
+        text = text.replace(re, renderRef(ref));
+        changes.push({ id: ref.id, action: 'updated', from: existingVersion, version: ref.version });
+    }
+    // Second pass: add the missing references. Prefer an existing <ItemGroup> that
+    // already holds a <PackageReference> (group them together); else append a fresh
+    // <ItemGroup> just before </Project>.
+    if (missing.length > 0) {
+        const block = missing.map((ref) => `${indent}${renderRef(ref)}`).join(eol);
+        const pkgItemGroupClose = findPackageReferenceItemGroupClose(text);
+        if (pkgItemGroupClose !== -1) {
+            // Insert the missing refs just before that ItemGroup's closing tag.
+            text = `${text.slice(0, pkgItemGroupClose)}${block}${eol}${text.slice(pkgItemGroupClose)}`;
+        }
+        else {
+            // No PackageReference ItemGroup — append a new one before </Project>.
+            const groupIndent = indent.length >= 2 ? indent.slice(0, Math.floor(indent.length / 2)) : '  ';
+            const newGroup = `${groupIndent}<ItemGroup>${eol}${block}${eol}${groupIndent}</ItemGroup>${eol}`;
+            const closeIdx = text.lastIndexOf('</Project>');
+            if (closeIdx === -1) {
+                // Not a recognizable csproj; append best-effort at EOF.
+                text = `${text}${eol}${newGroup}`;
+            }
+            else {
+                text = `${text.slice(0, closeIdx)}${newGroup}${text.slice(closeIdx)}`;
+            }
+        }
+        for (const ref of missing) {
+            changes.push({ id: ref.id, action: 'added', version: ref.version });
+        }
+    }
+    // Restore the required-order in `changes` to match `requiredRefs` for stable output.
+    const orderedChanges = requiredRefs
+        .map((ref) => changes.find((c) => c.id === ref.id))
+        .filter((c) => c !== undefined);
+    return {
+        text,
+        changed: orderedChanges.some((c) => c.action !== 'unchanged'),
+        changes: orderedChanges,
+    };
+}
+/**
+ * Return the index of the `</ItemGroup>` that closes the FIRST `<ItemGroup>`
+ * containing a `<PackageReference>`, or -1 when none exists. Used to group the
+ * added pins with the consumer's existing package references.
+ */
+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])) {
+            // The close tag starts at the end of the match minus its length.
+            const closeTag = '</ItemGroup>';
+            return m.index + m[0].length - closeTag.length;
+        }
+    }
+    return -1;
+}
+//# sourceMappingURL=csproj-deps.js.map

package/dist/utils/csproj-deps.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"csproj-deps.js","sourceRoot":"","sources":["../../src/utils/csproj-deps.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,wBAAwB,EAA8B,MAAM,iBAAiB,CAAC;AAiCvF,sDAAsD;AACtD,SAAS,YAAY,CAAC,KAAa;IACjC,OAAO,KAAK,CAAC,OAAO,CAAC,qBAAqB,EAAE,MAAM,CAAC,CAAC;AACtD,CAAC;AAED;;;;;GAKG;AACH,SAAS,eAAe,CAAC,EAAU;IACjC,MAAM,KAAK,GAAG,YAAY,CAAC,EAAE,CAAC,CAAC;IAC/B,qFAAqF;IACrF,gFAAgF;IAChF,gEAAgE;IAChE,OAAO,IAAI,MAAM,CACf,iDAAiD,KAAK,sEAAsE;QAC1H,GAAG;QACH,mFAAmF,KAAK,oCAAoC,EAC9H,GAAG,CACJ,CAAC;AACJ,CAAC;AAED,0EAA0E;AAC1E,SAAS,SAAS,CAAC,GAA0B;IAC3C,OAAO,8BAA8B,GAAG,CAAC,EAAE,cAAc,GAAG,CAAC,OAAO,MAAM,CAAC;AAC7E,CAAC;AAED;;;GAGG;AACH,SAAS,YAAY,CAAC,IAAY;IAChC,MAAM,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,+BAA+B,CAAC,CAAC;IACtD,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC;AAC3B,CAAC;AAED;;;;GAIG;AACH,SAAS,SAAS,CAAC,IAAY;IAC7B,MAAM,IAAI,GAAG,CAAC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC,CAAC,MAAM,CAAC;IAChD,MAAM,EAAE,GAAG,CAAC,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC,MAAM,GAAG,IAAI,CAAC;IACnD,OAAO,IAAI,GAAG,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC;AACnC,CAAC;AAED,MAAM,UAAU,yBAAyB,CACvC,UAAkB,EAClB,eAAiD,wBAAwB;IAEzE,MAAM,OAAO,GAAwB,EAAE,CAAC;IACxC,IAAI,IAAI,GAAG,UAAU,CAAC;IACtB,MAAM,MAAM,GAAG,YAAY,CAAC,IAAI,CAAC,CAAC;IAClC,MAAM,GAAG,GAAG,SAAS,CAAC,IAAI,CAAC,CAAC;IAE5B,yEAAyE;IACzE,0EAA0E;IAC1E,MAAM,OAAO,GAA4B,EAAE,CAAC;IAE5C,KAAK,MAAM,GAAG,IAAI,YAAY,EAAE,CAAC;QAC/B,MAAM,EAAE,GAAG,eAAe,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QACnC,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;QAC7B,IAAI,CAAC,KAAK,EAAE,CAAC;YACX,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;YAClB,SAAS;QACX,CAAC;QACD,MAAM,eAAe,GAAG,KAAK,CAAC,CAAC,CAAC,IAAI,KAAK,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;QACnD,IAAI,eAAe,KAAK,GAAG,CAAC,OAAO,EAAE,CAAC;YACpC,OAAO,CAAC,IAAI,CAAC,EAAE,EAAE,EAAE,GAAG,CAAC,EAAE,EAAE,MAAM,EAAE,WAAW,EAAE,OAAO,EAAE,GAAG,CAAC,OAAO,EAAE,CAAC,CAAC;YACxE,SAAS;QACX,CAAC;QACD,wEAAwE;QACxE,IAAI,GAAG,IAAI,CAAC,OAAO,CAAC,EAAE,EAAE,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC;QACxC,OAAO,CAAC,IAAI,CAAC,EAAE,EAAE,EAAE,GAAG,CAAC,EAAE,EAAE,MAAM,EAAE,SAAS,EAAE,IAAI,EAAE,eAAe,EAAE,OAAO,EAAE,GAAG,CAAC,OAAO,EAAE,CAAC,CAAC;IAC/F,CAAC;IAED,+EAA+E;IAC/E,gFAAgF;IAChF,sCAAsC;IACtC,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACvB,MAAM,KAAK,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,MAAM,GAAG,SAAS,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QAE3E,MAAM,iBAAiB,GAAG,kCAAkC,CAAC,IAAI,CAAC,CAAC;QACnE,IAAI,iBAAiB,KAAK,CAAC,CAAC,EAAE,CAAC;YAC7B,oEAAoE;YACpE,IAAI,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,iBAAiB,CAAC,GAAG,KAAK,GAAG,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,iBAAiB,CAAC,EAAE,CAAC;QAC7F,CAAC;aAAM,CAAC;YACN,sEAAsE;YACtE,MAAM,WAAW,GAAG,MAAM,CAAC,MAAM,IAAI,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;YAC/F,MAAM,QAAQ,GAAG,GAAG,WAAW,cAAc,GAAG,GAAG,KAAK,GAAG,GAAG,GAAG,WAAW,eAAe,GAAG,EAAE,CAAC;YACjG,MAAM,QAAQ,GAAG,IAAI,CAAC,WAAW,CAAC,YAAY,CAAC,CAAC;YAChD,IAAI,QAAQ,KAAK,CAAC,CAAC,EAAE,CAAC;gBACpB,wDAAwD;gBACxD,IAAI,GAAG,GAAG,IAAI,GAAG,GAAG,GAAG,QAAQ,EAAE,CAAC;YACpC,CAAC;iBAAM,CAAC;gBACN,IAAI,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,QAAQ,CAAC,GAAG,QAAQ,GAAG,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,EAAE,CAAC;YACxE,CAAC;QACH,CAAC;QAED,KAAK,MAAM,GAAG,IAAI,OAAO,EAAE,CAAC;YAC1B,OAAO,CAAC,IAAI,CAAC,EAAE,EAAE,EAAE,GAAG,CAAC,EAAE,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,EAAE,GAAG,CAAC,OAAO,EAAE,CAAC,CAAC;QACtE,CAAC;IACH,CAAC;IAED,qFAAqF;IACrF,MAAM,cAAc,GAAG,YAAY;SAChC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,GAAG,CAAC,EAAE,CAAC,CAAC;SAClD,MAAM,CAAC,CAAC,CAAC,EAA0B,EAAE,CAAC,CAAC,KAAK,SAAS,CAAC,CAAC;IAE1D,OAAO;QACL,IAAI;QACJ,OAAO,EAAE,cAAc,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,KAAK,WAAW,CAAC;QAC7D,OAAO,EAAE,cAAc;KACxB,CAAC;AACJ,CAAC;AAED;;;;GAIG;AACH,SAAS,kCAAkC,CAAC,IAAY;IACtD,MAAM,WAAW,GAAG,6CAA6C,CAAC;IAClE,IAAI,CAAyB,CAAC;IAC9B,OAAO,CAAC,CAAC,GAAG,WAAW,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,KAAK,IAAI,EAAE,CAAC;QAC7C,IAAI,sBAAsB,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;YACtC,iEAAiE;YACjE,MAAM,QAAQ,GAAG,cAAc,CAAC;YAChC,OAAO,CAAC,CAAC,KAAK,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,GAAG,QAAQ,CAAC,MAAM,CAAC;QACjD,CAAC;IACH,CAAC;IACD,OAAO,CAAC,CAAC,CAAC;AACZ,CAAC"}

package/dist/utils/unzip.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Minimal, dependency-free ZIP reader for the addon-install path. Parses the ZIP
+ * central directory and inflates each entry (STORED `0` + DEFLATE `8` — the only
+ * two compression methods the GitHub release `zip -r` produces). Pure: takes the
+ * archive bytes, returns `{ path, bytes }` entries; performs NO filesystem writes
+ * (the caller decides where the files land, after path-safety checks).
+ *
+ * This avoids adding a native/3rd-party unzip dependency to the lean `godot-cli`
+ * package while staying cross-platform (no shelling out to a system `unzip`).
+ * Exported for unit tests.
+ */
+export interface ZipEntry {
+    /** The entry's path inside the archive, using forward slashes. */
+    path: string;
+    /** Decompressed bytes. Empty for directory entries. */
+    bytes: Buffer;
+    /** True when the entry is a directory (path ends with `/`). */
+    isDirectory: boolean;
+}
+/**
+ * Parse a ZIP archive buffer into its entries. Throws a descriptive Error on a
+ * malformed archive (the caller wraps this into a structured failure — it never
+ * propagates past the library's public boundary).
+ */
+export declare function parseZip(buffer: Buffer): ZipEntry[];

package/dist/utils/unzip.js

@@ -0,0 +1,79 @@
+import * as zlib from 'zlib';
+// ZIP signatures.
+const EOCD_SIGNATURE = 0x06054b50; // End Of Central Directory
+const CDH_SIGNATURE = 0x02014b50; // Central Directory Header
+const LFH_SIGNATURE = 0x04034b50; // Local File Header
+/**
+ * Parse a ZIP archive buffer into its entries. Throws a descriptive Error on a
+ * malformed archive (the caller wraps this into a structured failure — it never
+ * propagates past the library's public boundary).
+ */
+export function parseZip(buffer) {
+    const eocdOffset = findEndOfCentralDirectory(buffer);
+    if (eocdOffset === -1) {
+        throw new Error('Invalid zip: End Of Central Directory record not found.');
+    }
+    const entryCount = buffer.readUInt16LE(eocdOffset + 10);
+    const centralDirOffset = buffer.readUInt32LE(eocdOffset + 16);
+    const entries = [];
+    let ptr = centralDirOffset;
+    for (let i = 0; i < entryCount; i++) {
+        if (buffer.readUInt32LE(ptr) !== CDH_SIGNATURE) {
+            throw new Error(`Invalid zip: bad central directory header at entry ${i}.`);
+        }
+        const compressionMethod = buffer.readUInt16LE(ptr + 10);
+        const compressedSize = buffer.readUInt32LE(ptr + 20);
+        const fileNameLength = buffer.readUInt16LE(ptr + 28);
+        const extraFieldLength = buffer.readUInt16LE(ptr + 30);
+        const commentLength = buffer.readUInt16LE(ptr + 32);
+        const localHeaderOffset = buffer.readUInt32LE(ptr + 42);
+        const fileName = buffer.toString('utf8', ptr + 46, ptr + 46 + fileNameLength);
+        const bytes = readLocalEntry(buffer, localHeaderOffset, compressionMethod, compressedSize);
+        entries.push({
+            path: fileName.replace(/\\/g, '/'),
+            bytes,
+            isDirectory: fileName.endsWith('/'),
+        });
+        ptr += 46 + fileNameLength + extraFieldLength + commentLength;
+    }
+    return entries;
+}
+/** Read + decompress a single entry given its central-directory metadata. */
+function readLocalEntry(buffer, localHeaderOffset, compressionMethod, compressedSize) {
+    if (buffer.readUInt32LE(localHeaderOffset) !== LFH_SIGNATURE) {
+        throw new Error('Invalid zip: bad local file header.');
+    }
+    // The local header repeats the name/extra lengths; the data starts after them.
+    const lfhNameLength = buffer.readUInt16LE(localHeaderOffset + 26);
+    const lfhExtraLength = buffer.readUInt16LE(localHeaderOffset + 28);
+    const dataStart = localHeaderOffset + 30 + lfhNameLength + lfhExtraLength;
+    const compressed = buffer.subarray(dataStart, dataStart + compressedSize);
+    if (compressionMethod === 0) {
+        // STORED — no compression.
+        return Buffer.from(compressed);
+    }
+    if (compressionMethod === 8) {
+        // DEFLATE (raw, no zlib header).
+        return zlib.inflateRawSync(compressed);
+    }
+    throw new Error(`Unsupported zip compression method ${compressionMethod}.`);
+}
+/**
+ * Locate the End Of Central Directory record by scanning backwards from EOF for
+ * its signature (the trailing comment is almost always empty, so it is usually
+ * the last 22 bytes — but we scan to be safe).
+ */
+function findEndOfCentralDirectory(buffer) {
+    const minEocdSize = 22;
+    if (buffer.length < minEocdSize)
+        return -1;
+    // Max comment length is 0xFFFF; scan that far back at most.
+    const scanStart = Math.max(0, buffer.length - minEocdSize - 0xffff);
+    for (let i = buffer.length - minEocdSize; i >= scanStart; i--) {
+        if (buffer.readUInt32LE(i) === EOCD_SIGNATURE) {
+            return i;
+        }
+    }
+    return -1;
+}
+//# sourceMappingURL=unzip.js.map

package/dist/utils/unzip.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"unzip.js","sourceRoot":"","sources":["../../src/utils/unzip.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,IAAI,MAAM,MAAM,CAAC;AAuB7B,kBAAkB;AAClB,MAAM,cAAc,GAAG,UAAU,CAAC,CAAC,2BAA2B;AAC9D,MAAM,aAAa,GAAG,UAAU,CAAC,CAAC,2BAA2B;AAC7D,MAAM,aAAa,GAAG,UAAU,CAAC,CAAC,oBAAoB;AAEtD;;;;GAIG;AACH,MAAM,UAAU,QAAQ,CAAC,MAAc;IACrC,MAAM,UAAU,GAAG,yBAAyB,CAAC,MAAM,CAAC,CAAC;IACrD,IAAI,UAAU,KAAK,CAAC,CAAC,EAAE,CAAC;QACtB,MAAM,IAAI,KAAK,CAAC,yDAAyD,CAAC,CAAC;IAC7E,CAAC;IAED,MAAM,UAAU,GAAG,MAAM,CAAC,YAAY,CAAC,UAAU,GAAG,EAAE,CAAC,CAAC;IACxD,MAAM,gBAAgB,GAAG,MAAM,CAAC,YAAY,CAAC,UAAU,GAAG,EAAE,CAAC,CAAC;IAE9D,MAAM,OAAO,GAAe,EAAE,CAAC;IAC/B,IAAI,GAAG,GAAG,gBAAgB,CAAC;IAE3B,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,UAAU,EAAE,CAAC,EAAE,EAAE,CAAC;QACpC,IAAI,MAAM,CAAC,YAAY,CAAC,GAAG,CAAC,KAAK,aAAa,EAAE,CAAC;YAC/C,MAAM,IAAI,KAAK,CAAC,sDAAsD,CAAC,GAAG,CAAC,CAAC;QAC9E,CAAC;QACD,MAAM,iBAAiB,GAAG,MAAM,CAAC,YAAY,CAAC,GAAG,GAAG,EAAE,CAAC,CAAC;QACxD,MAAM,cAAc,GAAG,MAAM,CAAC,YAAY,CAAC,GAAG,GAAG,EAAE,CAAC,CAAC;QACrD,MAAM,cAAc,GAAG,MAAM,CAAC,YAAY,CAAC,GAAG,GAAG,EAAE,CAAC,CAAC;QACrD,MAAM,gBAAgB,GAAG,MAAM,CAAC,YAAY,CAAC,GAAG,GAAG,EAAE,CAAC,CAAC;QACvD,MAAM,aAAa,GAAG,MAAM,CAAC,YAAY,CAAC,GAAG,GAAG,EAAE,CAAC,CAAC;QACpD,MAAM,iBAAiB,GAAG,MAAM,CAAC,YAAY,CAAC,GAAG,GAAG,EAAE,CAAC,CAAC;QAExD,MAAM,QAAQ,GAAG,MAAM,CAAC,QAAQ,CAAC,MAAM,EAAE,GAAG,GAAG,EAAE,EAAE,GAAG,GAAG,EAAE,GAAG,cAAc,CAAC,CAAC;QAE9E,MAAM,KAAK,GAAG,cAAc,CAAC,MAAM,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,cAAc,CAAC,CAAC;QAC3F,OAAO,CAAC,IAAI,CAAC;YACX,IAAI,EAAE,QAAQ,CAAC,OAAO,CAAC,KAAK,EAAE,GAAG,CAAC;YAClC,KAAK;YACL,WAAW,EAAE,QAAQ,CAAC,QAAQ,CAAC,GAAG,CAAC;SACpC,CAAC,CAAC;QAEH,GAAG,IAAI,EAAE,GAAG,cAAc,GAAG,gBAAgB,GAAG,aAAa,CAAC;IAChE,CAAC;IAED,OAAO,OAAO,CAAC;AACjB,CAAC;AAED,6EAA6E;AAC7E,SAAS,cAAc,CACrB,MAAc,EACd,iBAAyB,EACzB,iBAAyB,EACzB,cAAsB;IAEtB,IAAI,MAAM,CAAC,YAAY,CAAC,iBAAiB,CAAC,KAAK,aAAa,EAAE,CAAC;QAC7D,MAAM,IAAI,KAAK,CAAC,qCAAqC,CAAC,CAAC;IACzD,CAAC;IACD,+EAA+E;IAC/E,MAAM,aAAa,GAAG,MAAM,CAAC,YAAY,CAAC,iBAAiB,GAAG,EAAE,CAAC,CAAC;IAClE,MAAM,cAAc,GAAG,MAAM,CAAC,YAAY,CAAC,iBAAiB,GAAG,EAAE,CAAC,CAAC;IACnE,MAAM,SAAS,GAAG,iBAAiB,GAAG,EAAE,GAAG,aAAa,GAAG,cAAc,CAAC;IAC1E,MAAM,UAAU,GAAG,MAAM,CAAC,QAAQ,CAAC,SAAS,EAAE,SAAS,GAAG,cAAc,CAAC,CAAC;IAE1E,IAAI,iBAAiB,KAAK,CAAC,EAAE,CAAC;QAC5B,2BAA2B;QAC3B,OAAO,MAAM,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;IACjC,CAAC;IACD,IAAI,iBAAiB,KAAK,CAAC,EAAE,CAAC;QAC5B,iCAAiC;QACjC,OAAO,IAAI,CAAC,cAAc,CAAC,UAAU,CAAC,CAAC;IACzC,CAAC;IACD,MAAM,IAAI,KAAK,CAAC,sCAAsC,iBAAiB,GAAG,CAAC,CAAC;AAC9E,CAAC;AAED;;;;GAIG;AACH,SAAS,yBAAyB,CAAC,MAAc;IAC/C,MAAM,WAAW,GAAG,EAAE,CAAC;IACvB,IAAI,MAAM,CAAC,MAAM,GAAG,WAAW;QAAE,OAAO,CAAC,CAAC,CAAC;IAC3C,4DAA4D;IAC5D,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,MAAM,CAAC,MAAM,GAAG,WAAW,GAAG,MAAM,CAAC,CAAC;IACpE,KAAK,IAAI,CAAC,GAAG,MAAM,CAAC,MAAM,GAAG,WAAW,EAAE,CAAC,IAAI,SAAS,EAAE,CAAC,EAAE,EAAE,CAAC;QAC9D,IAAI,MAAM,CAAC,YAAY,CAAC,CAAC,CAAC,KAAK,cAAc,EAAE,CAAC;YAC9C,OAAO,CAAC,CAAC;QACX,CAAC;IACH,CAAC;IACD,OAAO,CAAC,CAAC,CAAC;AACZ,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "godot-cli",
-  "version": "0.11.1",
+  "version": "0.12.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",