unity-mcp-cli 0.83.1 → 0.84.0

package/dist/utils/enroll.js

@@ -0,0 +1,251 @@
+// Copyright (c) 2024 Ivan Murzak. All rights reserved.
+// Licensed under the Apache License, Version 2.0.
+import * as fs from 'fs';
+import * as path from 'path';
+import { CLOUD_SERVER_BASE_URL } from './config.js';
+import { deriveProjectPin } from './port.js';
+import { agentRegistry, MCP_SERVER_NAME } from './agents.js';
+import { writeProjectMarker } from './project-marker.js';
+/**
+ * Agent-driven enrollment (D13): redeem a one-time enrollment code — minted by the server's
+ * `enroll_engine_plugin` tool from an already-authorized agent session — for a plugin credential,
+ * with NO second browser hop. The redeemed credential is planted in the shared machine store, the
+ * server target it was minted for is recorded in the project marker, and the D14 project pin is
+ * upserted into any existing project-local agent config so the plugin boots pointed at the right
+ * hub. Codes are burned server-side on first redeem attempt; a spent/invalid code yields a uniform
+ * error surfaced here as an actionable message.
+ */
+/** Raised on any enrollment-redeem failure. Carries the HTTP status when one was received. */
+export class EnrollmentError extends Error {
+    constructor(message, status) {
+        super(message);
+        this.name = 'EnrollmentError';
+        this.status = status;
+    }
+}
+function nonEmptyString(value) {
+    return typeof value === 'string' && value.length > 0 ? value : undefined;
+}
+function numberOrUndefined(value) {
+    return typeof value === 'number' && Number.isFinite(value) ? value : undefined;
+}
+/**
+ * Normalize the redeem response. The Authorization Server's JSON key casing is not re-derivable
+ * from this repo (the AS lives in a separate service), so both snake_case and camelCase variants
+ * of every field are accepted defensively; `expires_in` seconds are converted to an absolute
+ * `expiresAt` ISO timestamp when no explicit `expires_at` is present.
+ */
+export function normalizeRedeemResponse(data) {
+    const accessToken = nonEmptyString(data.access_token) ?? nonEmptyString(data.accessToken);
+    const refreshToken = nonEmptyString(data.refresh_token) ?? nonEmptyString(data.refreshToken);
+    const serverTarget = nonEmptyString(data.server_target) ??
+        nonEmptyString(data.serverTarget) ??
+        nonEmptyString(data.server_target_url) ??
+        nonEmptyString(data.serverTargetUrl);
+    const subject = nonEmptyString(data.subject) ?? nonEmptyString(data.sub);
+    let expiresAt = nonEmptyString(data.expires_at) ?? nonEmptyString(data.expiresAt);
+    const expiresIn = numberOrUndefined(data.expires_in) ?? numberOrUndefined(data.expiresIn);
+    if (!expiresAt && expiresIn !== undefined) {
+        expiresAt = new Date(Date.now() + expiresIn * 1000).toISOString();
+    }
+    return { accessToken, refreshToken, expiresAt, serverTarget, subject };
+}
+/**
+ * Redeem an enrollment code against `POST <baseUrl>/api/auth/enroll/redeem` with body
+ * `{enroll_code}`. The code travels only in the request BODY (never a query string). A non-2xx
+ * response is surfaced as an actionable `EnrollmentError` (invalid/expired/already-used codes all
+ * return a uniform server error; burn-on-first-attempt is server-side).
+ */
+export async function redeemEnrollmentCode(code, opts = {}) {
+    const baseUrl = opts.baseUrl ?? CLOUD_SERVER_BASE_URL;
+    const doFetch = opts.fetchImpl ?? fetch;
+    const url = `${baseUrl}/api/auth/enroll/redeem`;
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), opts.timeoutMs ?? 30000);
+    let response;
+    try {
+        response = await doFetch(url, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({ enroll_code: code }),
+            signal: controller.signal,
+        });
+    }
+    catch (err) {
+        throw new EnrollmentError(`Could not reach the enrollment server at ${url}: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    finally {
+        clearTimeout(timer);
+    }
+    if (!response.ok) {
+        throw new EnrollmentError(`Enrollment failed (HTTP ${response.status}). The enrollment code may be invalid, expired, ` +
+            `or already used — ask the agent to issue a fresh code and try again.`, response.status);
+    }
+    let data;
+    try {
+        data = (await response.json());
+    }
+    catch {
+        throw new EnrollmentError('Enrollment server returned a malformed (non-JSON) response.');
+    }
+    const credential = normalizeRedeemResponse(data);
+    if (!credential.accessToken) {
+        throw new EnrollmentError('Enrollment response did not contain an access token.');
+    }
+    return credential;
+}
+// ---------------------------------------------------------------------------
+// Enrollment code resolution (--enroll <code> vs --enroll-stdin)
+// ---------------------------------------------------------------------------
+/**
+ * Resolve the enrollment code from `--enroll <code>` (argv) or `--enroll-stdin` (stdin), enforcing
+ * mutual exclusion. `--enroll-stdin` reads via the injected `readStdin` so the code NEVER lands in
+ * argv / shell history. `readStdin` is only invoked in the stdin mode.
+ */
+export function resolveEnrollCode(opts, readStdin) {
+    if (opts.enroll && opts.enrollStdin) {
+        throw new Error('Use either --enroll <code> or --enroll-stdin, not both.');
+    }
+    if (opts.enrollStdin) {
+        const code = readStdin().trim();
+        if (!code)
+            throw new Error('No enrollment code received on stdin.');
+        return code;
+    }
+    if (opts.enroll) {
+        const code = opts.enroll.trim();
+        if (!code)
+            throw new Error('Enrollment code (--enroll) is empty.');
+        return code;
+    }
+    throw new Error('An enrollment code is required: pass --enroll <code> or --enroll-stdin.');
+}
+// ---------------------------------------------------------------------------
+// Project pin upsert (D14)
+// ---------------------------------------------------------------------------
+/**
+ * Add (or replace) the `/p/<pin>` routing segment on a config URL so an agent session launched in
+ * this project folder routes strictly to this project's engine (design 06 D14). Existing `/p/<pin>`
+ * segments are replaced; the port / host / scheme are preserved.
+ */
+export function pinUrl(rawUrl, pin) {
+    const stripExistingPin = (segments) => {
+        const idx = segments.findIndex((s) => s === 'p');
+        if (idx >= 0 && idx === segments.length - 2 && /^[0-9a-f]{8}$/i.test(segments[idx + 1])) {
+            return segments.slice(0, idx);
+        }
+        return segments;
+    };
+    try {
+        const url = new URL(rawUrl);
+        let segments = stripExistingPin(url.pathname.split('/').filter(Boolean));
+        segments = [...segments, 'p', pin];
+        url.pathname = '/' + segments.join('/');
+        return url.toString().replace(/\/$/, '');
+    }
+    catch {
+        const base = rawUrl.replace(/\/+$/, '').replace(/\/p\/[0-9a-f]{8}$/i, '');
+        return `${base}/p/${pin}`;
+    }
+}
+/**
+ * The exact project-root STRING to feed into ProjectIdentity so the CLI-derived pin matches the
+ * plugin's. The Unity plugin registers with `ProjectIdentity.DerivePin(UnityMcpPluginEditor
+ * .ProjectRootPath)`, where `ProjectRootPath => Path.GetDirectoryName(Application.dataPath)`.
+ * `Application.dataPath` is forward-slash on EVERY platform (incl. Windows: `C:/proj/Assets`), so
+ * the plugin hashes a forward-slash root like `C:/proj`. Node's `path.resolve` yields BACKSLASHES
+ * on Windows (`C:\proj`), which the ProjectIdentity golden vectors hash to a DIFFERENT pin — so we
+ * convert separators to `/` here (a no-op on POSIX) to route to the same engine instance.
+ */
+export function projectRootForIdentity(projectPath) {
+    return path.resolve(projectPath).replace(/\\/g, '/');
+}
+/**
+ * Upsert the project pin into every EXISTING project-local (project-scoped) JSON agent config that
+ * carries an `ai-game-developer` server entry with a `url` / `serverUrl`. Global client config
+ * files (Claude Desktop, Antigravity, Cline, the Copilot CLI) are never touched — the golden path
+ * writes no user-global entry. TOML (Codex) configs are left to the server binary's own
+ * `configure`. Returns the list of files actually rewritten.
+ */
+export function upsertProjectPinIntoConfigs(projectPath, pin) {
+    const resolvedProject = path.resolve(projectPath);
+    const updatedFiles = [];
+    for (const agent of agentRegistry) {
+        if (agent.configFormat !== 'json')
+            continue;
+        const configPath = agent.getConfigPath(resolvedProject);
+        // Project-scoped only: the config path must live inside the project directory.
+        const relative = path.relative(resolvedProject, configPath);
+        if (relative.startsWith('..') || path.isAbsolute(relative))
+            continue;
+        if (!fs.existsSync(configPath))
+            continue;
+        let root;
+        try {
+            const parsed = JSON.parse(fs.readFileSync(configPath, 'utf-8'));
+            if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed))
+                continue;
+            root = parsed;
+        }
+        catch {
+            continue;
+        }
+        const body = root[agent.bodyPath];
+        if (!body || typeof body !== 'object' || Array.isArray(body))
+            continue;
+        const entry = body[MCP_SERVER_NAME];
+        if (!entry || typeof entry !== 'object' || Array.isArray(entry))
+            continue;
+        const entryRecord = entry;
+        let changed = false;
+        for (const key of ['url', 'serverUrl']) {
+            const current = entryRecord[key];
+            if (typeof current === 'string' && current.length > 0) {
+                const pinned = pinUrl(current, pin);
+                if (pinned !== current) {
+                    entryRecord[key] = pinned;
+                    changed = true;
+                }
+            }
+        }
+        if (changed) {
+            fs.writeFileSync(configPath, JSON.stringify(root, null, 2) + '\n');
+            updatedFiles.push(configPath);
+        }
+    }
+    return { updatedFiles };
+}
+/**
+ * Execute the full enrollment side effect: redeem → persist the plugin credential to the SHARED
+ * machine store → write the project marker with the server target → upsert the D14 pin into
+ * existing project-local configs. NEVER writes a project token file / `cloudToken` config.
+ */
+export async function runEnroll(opts) {
+    const credential = await redeemEnrollmentCode(opts.code, {
+        baseUrl: opts.baseUrl,
+        fetchImpl: opts.fetchImpl,
+    });
+    const serverTarget = credential.serverTarget ?? opts.baseUrl ?? CLOUD_SERVER_BASE_URL;
+    // Persist to the shared machine credential store (0600 / DPAPI) — never a project file.
+    opts.store.write({
+        accessToken: credential.accessToken,
+        refreshToken: credential.refreshToken,
+        expiresAt: credential.expiresAt,
+        serverTarget,
+        subject: credential.subject,
+    });
+    // Record the enrolled server target in the committable project marker.
+    const markerPath = writeProjectMarker(opts.projectPath, { serverTarget });
+    // Upsert the D14 pin into existing project-local agent configs. The pin is derived from the
+    // forward-slash project root so it matches the plugin's pin (see projectRootForIdentity).
+    const pin = deriveProjectPin(projectRootForIdentity(opts.projectPath));
+    const { updatedFiles } = upsertProjectPinIntoConfigs(opts.projectPath, pin);
+    return {
+        serverTarget,
+        pin,
+        credentialPath: opts.store.credentialsPath,
+        markerPath,
+        pinnedConfigs: updatedFiles,
+    };
+}
+//# sourceMappingURL=enroll.js.map

package/dist/utils/enroll.js.map

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

package/dist/utils/machine-credentials.d.ts

@@ -0,0 +1,64 @@
+/**
+ * TypeScript client of the shared machine credential store — the same on-disk contract the
+ * plugin's C# `MachineCredentialStore` (MCP-Plugin-dotnet, com.IvanMurzak.McpPlugin.AgentConfig)
+ * reads and writes. A single ai-game.dev account credential lives once per machine at
+ * `~/.ai-game-dev/credentials.json`, so `login` writes it here and every engine plugin/CLI reads
+ * it — sign-in happens once per machine, never per project, and the credential is NEVER written
+ * into a project file / VCS.
+ *
+ * At-rest protection matches the C# store byte-for-byte so the plugin can read what the CLI wrote:
+ *   - POSIX  — plaintext JSON, file mode 0600, inside a 0700 directory.
+ *   - Windows — DPAPI-encrypted (CurrentUser scope, no entropy) via
+ *     System.Security.Cryptography.ProtectedData, invoked through PowerShell. This is
+ *     interoperable with the C# store's CryptProtectData/CryptUnprotectData (the description
+ *     string and CRYPTPROTECT_UI_FORBIDDEN flag do not affect decryptability).
+ */
+/** Directory name under the user home (or a project root) that holds the store. */
+export declare const MACHINE_STORE_DIR_NAME = ".ai-game-dev";
+/** File name of the secret credential document. */
+export declare const CREDENTIALS_FILE_NAME = "credentials.json";
+/**
+ * The secret credential material persisted in the store. Mirrors the C# `MachineCredentials`
+ * schema (camelCase JSON keys). Unknown fields are preserved on read for forward-compatibility.
+ */
+export interface MachineCredentials {
+    /** Schema version of the persisted document (currently 1). */
+    version?: number;
+    /** The current short-lived JWT access token (MCP audience). */
+    accessToken?: string;
+    /** The rotating refresh token used to mint a new access token before `expiresAt`. */
+    refreshToken?: string;
+    /** ISO-8601 absolute expiry of `accessToken`; used to schedule proactive refresh. */
+    expiresAt?: string;
+    /** The server target the credential was issued for (hosted https://ai-game.dev or a local URL). */
+    serverTarget?: string;
+    /** The account id (`sub`) the credential resolves to. Audit/diagnostic only. */
+    subject?: string;
+    [key: string]: unknown;
+}
+/**
+ * The shared machine credential store. Defaults to `~/.ai-game-dev/`; pass an explicit
+ * `baseDirectory` for tests or for the `--project` per-project store
+ * (`<project>/.ai-game-dev/`).
+ */
+export declare class MachineCredentialStore {
+    private readonly _baseDirectory;
+    constructor(baseDirectory?: string);
+    /** Absolute path of the store directory. */
+    get baseDirectory(): string;
+    /** Absolute path of the secret credential file. */
+    get credentialsPath(): string;
+    /** True when a credential file exists in the store. */
+    get exists(): boolean;
+    /**
+     * Encrypt (Windows) / restrict (POSIX) and write `credentials` to the store, creating the
+     * store directory with owner-only permissions if needed. `version` is always written as 1;
+     * undefined fields are omitted (matching the C# `WhenWritingNull` policy).
+     */
+    write(credentials: MachineCredentials): void;
+    /** Read and decrypt the stored credentials, or null when none are present. */
+    read(): MachineCredentials | null;
+    /** Delete the stored credentials (sign-out). No-op when none exist. */
+    delete(): void;
+    private ensureBaseDirectory;
+}

package/dist/utils/machine-credentials.js

@@ -0,0 +1,114 @@
+// Copyright (c) 2024 Ivan Murzak. All rights reserved.
+// Licensed under the Apache License, Version 2.0.
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+import { execFileSync } from 'child_process';
+/**
+ * TypeScript client of the shared machine credential store — the same on-disk contract the
+ * plugin's C# `MachineCredentialStore` (MCP-Plugin-dotnet, com.IvanMurzak.McpPlugin.AgentConfig)
+ * reads and writes. A single ai-game.dev account credential lives once per machine at
+ * `~/.ai-game-dev/credentials.json`, so `login` writes it here and every engine plugin/CLI reads
+ * it — sign-in happens once per machine, never per project, and the credential is NEVER written
+ * into a project file / VCS.
+ *
+ * At-rest protection matches the C# store byte-for-byte so the plugin can read what the CLI wrote:
+ *   - POSIX  — plaintext JSON, file mode 0600, inside a 0700 directory.
+ *   - Windows — DPAPI-encrypted (CurrentUser scope, no entropy) via
+ *     System.Security.Cryptography.ProtectedData, invoked through PowerShell. This is
+ *     interoperable with the C# store's CryptProtectData/CryptUnprotectData (the description
+ *     string and CRYPTPROTECT_UI_FORBIDDEN flag do not affect decryptability).
+ */
+/** Directory name under the user home (or a project root) that holds the store. */
+export const MACHINE_STORE_DIR_NAME = '.ai-game-dev';
+/** File name of the secret credential document. */
+export const CREDENTIALS_FILE_NAME = 'credentials.json';
+const isWindows = process.platform === 'win32';
+/**
+ * The shared machine credential store. Defaults to `~/.ai-game-dev/`; pass an explicit
+ * `baseDirectory` for tests or for the `--project` per-project store
+ * (`<project>/.ai-game-dev/`).
+ */
+export class MachineCredentialStore {
+    constructor(baseDirectory) {
+        this._baseDirectory = baseDirectory ?? path.join(os.homedir(), MACHINE_STORE_DIR_NAME);
+    }
+    /** Absolute path of the store directory. */
+    get baseDirectory() {
+        return this._baseDirectory;
+    }
+    /** Absolute path of the secret credential file. */
+    get credentialsPath() {
+        return path.join(this._baseDirectory, CREDENTIALS_FILE_NAME);
+    }
+    /** True when a credential file exists in the store. */
+    get exists() {
+        return fs.existsSync(this.credentialsPath);
+    }
+    /**
+     * Encrypt (Windows) / restrict (POSIX) and write `credentials` to the store, creating the
+     * store directory with owner-only permissions if needed. `version` is always written as 1;
+     * undefined fields are omitted (matching the C# `WhenWritingNull` policy).
+     */
+    write(credentials) {
+        this.ensureBaseDirectory();
+        const document = { ...credentials, version: 1 };
+        const json = JSON.stringify(document, null, 2);
+        const plaintext = Buffer.from(json, 'utf-8');
+        const bytes = isWindows ? dpapiTransform('Protect', plaintext) : plaintext;
+        fs.writeFileSync(this.credentialsPath, bytes);
+        if (!isWindows) {
+            fs.chmodSync(this.credentialsPath, 0o600);
+        }
+    }
+    /** Read and decrypt the stored credentials, or null when none are present. */
+    read() {
+        if (!fs.existsSync(this.credentialsPath)) {
+            return null;
+        }
+        const raw = fs.readFileSync(this.credentialsPath);
+        if (raw.length === 0) {
+            return null;
+        }
+        const plaintext = isWindows ? dpapiTransform('Unprotect', raw) : raw;
+        const json = plaintext.toString('utf-8');
+        if (json.trim().length === 0) {
+            return null;
+        }
+        return JSON.parse(json);
+    }
+    /** Delete the stored credentials (sign-out). No-op when none exist. */
+    delete() {
+        if (fs.existsSync(this.credentialsPath)) {
+            fs.rmSync(this.credentialsPath);
+        }
+    }
+    ensureBaseDirectory() {
+        fs.mkdirSync(this._baseDirectory, { recursive: true });
+        if (!isWindows) {
+            fs.chmodSync(this._baseDirectory, 0o700);
+        }
+    }
+}
+/**
+ * Run a Windows DPAPI Protect/Unprotect round trip through PowerShell's
+ * System.Security.Cryptography.ProtectedData (CurrentUser scope, no entropy) — interoperable
+ * with the C# store's CryptProtectData/CryptUnprotectData. Input and output are passed as
+ * base64 through an environment variable so the plaintext never lands in argv or the process
+ * table. Only ever invoked on Windows.
+ */
+function dpapiTransform(action, input) {
+    const script = "$ErrorActionPreference='Stop';" +
+        'Add-Type -AssemblyName System.Security;' +
+        '$in=[Convert]::FromBase64String($env:AIGD_DPAPI_IN);' +
+        `$out=[System.Security.Cryptography.ProtectedData]::${action}($in,$null,[System.Security.Cryptography.DataProtectionScope]::CurrentUser);` +
+        '[Convert]::ToBase64String($out)';
+    const stdout = execFileSync('powershell.exe', ['-NoProfile', '-NonInteractive', '-Command', script], {
+        encoding: 'utf-8',
+        env: { ...process.env, AIGD_DPAPI_IN: input.toString('base64') },
+        timeout: 20000,
+        windowsHide: true,
+    });
+    return Buffer.from(stdout.trim(), 'base64');
+}
+//# sourceMappingURL=machine-credentials.js.map

package/dist/utils/machine-credentials.js.map

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

package/dist/utils/managed-server.d.ts

@@ -0,0 +1,95 @@
+/**
+ * The CLI's MANAGED server directory — the machine-shared home the `install-plugin --with-server`
+ * download lands in, and the directory `configure --agent` proxies to. Lives beside the shared
+ * machine credential store (`~/.ai-game-dev/`) so the server binary is fetched once per machine,
+ * not once per project, and is NEVER on PATH (design 06/09: the binary lives in the CLI's managed
+ * dir). Layout mirrors the plugin's `Library/mcp-server/<rid>/` — one folder per RID + a `version`
+ * marker.
+ */
+export declare function managedServerRootDir(homeDir?: string): string;
+export declare function managedServerDir(rid: string, homeDir?: string): string;
+/** The server executable file name for a RID (`.exe` suffix on Windows RIDs). */
+export declare function managedServerBinaryName(rid: string): string;
+export declare function managedServerBinaryPath(rid: string, homeDir?: string): string;
+/** Absolute path of the `version` marker recording which server version is staged for a RID. */
+export declare function managedServerVersionPath(rid: string, homeDir?: string): string;
+/** The release-asset zip NAME for a RID (`gamedev-mcp-server-<rid>.zip`) — the SHA256SUMS key. */
+export declare function serverZipName(rid: string): string;
+/** The GitHub release download URL of the per-RID server zip, pinned to `version`. */
+export declare function serverZipUrl(rid: string, version: string): string;
+/** The GitHub release download URL of the `SHA256SUMS` integrity manifest, pinned to `version`. */
+export declare function serverShaSumsUrl(version: string): string;
+/**
+ * Look up the expected SHA-256 (lowercase hex) for `fileName` in a `SHA256SUMS` manifest.
+ * Accepts the canonical `<hex>  <name>` line shape and the `<hex> *<name>` binary-mode variant.
+ * Returns null when no line names `fileName` (exact match — mirrors the C# exact-key Ordinal
+ * lookup), so a missing entry fails closed at the call site.
+ */
+export declare function parseSha256Sums(manifest: string, fileName: string): string | null;
+/** SHA-256 of a buffer as lowercase hex. */
+export declare function sha256Hex(buffer: Buffer): string;
+/**
+ * Extract a `.zip` into `destDir` using the best available platform archive tool. Node ships no
+ * zip reader, so this shells out: bsdtar (`tar -xf`, present on Windows 10+ and macOS) and `unzip`
+ * (POSIX) cover every supported host, with a PowerShell `Expand-Archive` fallback on Windows. The
+ * caller verifies the extracted binary exists afterwards, so a silent no-op tool is still caught.
+ */
+export declare function extractZip(zipPath: string, destDir: string): void;
+export interface DownloadServerOptions {
+    /** Host RID; defaults to `resolveHostRid()`. */
+    rid?: string;
+    /** Server version to fetch; defaults to `DEFAULT_SERVER_VERSION`. */
+    version?: string;
+    /**
+     * Offline/CI escape hatch: a local zip path OR a URL to fetch the zip from. When set, the
+     * download uses this source and the SHA256SUMS integrity gate is SKIPPED (explicit-trust
+     * override — mirrors the addon `--source` pattern). Otherwise the pinned release zip is fetched
+     * and verified fail-closed against the release's SHA256SUMS.
+     */
+    source?: string;
+    /** Home directory override (tests). */
+    homeDir?: string;
+    /** `fetch` injection (tests). */
+    fetchImpl?: typeof fetch;
+    /** Extraction injection (tests) — `(zipPath, destDir) => void`. */
+    extractImpl?: (zipPath: string, destDir: string) => void;
+    /** Optional progress reporter. */
+    onProgress?: (message: string) => void;
+}
+export interface DownloadServerResult {
+    rid: string;
+    version: string;
+    /** Absolute path of the published server binary. */
+    binaryPath: string;
+    /** True when the zip passed SHA256SUMS verification; false for a `--server-source` override. */
+    verified: boolean;
+}
+/**
+ * Download (or copy from `--server-source`), verify against the release SHA256SUMS (fail-closed),
+ * extract, and atomically publish the pinned GameDev-MCP-Server binary for the host RID into the
+ * CLI's managed directory. Never launches the binary. Returns the published path.
+ */
+export declare function downloadServerBinary(opts?: DownloadServerOptions): Promise<DownloadServerResult>;
+export interface ConfigureProxyOptions {
+    agentId: string;
+    projectPath: string;
+    /** Optional explicit server URL forwarded to the binary's `configure --url`. */
+    url?: string;
+    rid?: string;
+    homeDir?: string;
+    /** Runner injection (tests) — `(binaryPath, args, cwd) => void`. */
+    runImpl?: (binaryPath: string, args: string[], cwd: string) => void;
+}
+export interface ConfigureProxyResult {
+    binaryPath: string;
+    args: string[];
+    cwd: string;
+}
+/**
+ * Proxy `configure --agent <id>` to the managed GameDev-MCP-Server binary's `configure`
+ * subcommand (design 06/09 Phase 3) so the shared C# configurator registry — with the derived
+ * `port=` + `project=` pin — is reachable from the terminal. The binary derives the pin/port from
+ * its working directory, so we run it with `cwd` = the resolved project path. When no managed
+ * binary is installed, throws a clear, actionable error pointing at `install-plugin --with-server`.
+ */
+export declare function proxyConfigure(opts: ConfigureProxyOptions): ConfigureProxyResult;