@ai-agent-forge/agent-forge 0.85.0

package/dist/core/package-manager.js

@@ -0,0 +1,947 @@
+import { existsSync, mkdirSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { gt, maxSatisfying, rcompare } from "semver";
+import { CONFIG_DIR_NAME } from "../config.js";
+import { spawnProcess, spawnProcessSync } from "../utils/child-process.js";
+import { resolvePath as resolvePathWithBase } from "../utils/paths.js";
+import { isStdoutTakenOver } from "./output-guard.js";
+import { ensureGitIgnore, ensureNpmProject, getGitDependencyInstallArgs, getGitInstallPath, getGitInstallRoot, getGitUpdateMarkerPath, getInstalledNpmVersion, getManagedNpmInstallPath, getNpmCommand, getNpmInstallArgs, getNpmInstallRoot, getPackageManagerName, hasMissingGitDependencies, installedNpmMatchesConfiguredVersion, pruneEmptyGitParents, } from "./package-install-host.js";
+import { getEnv, isOfflineModeEnabled, runWithConcurrency } from "./package-process-runner.js";
+import { addAutoDiscoveredResources, collectPackageResources, createAccumulator, getTargetMap, resolveLocalEntries, toResolvedPaths, } from "./package-resource-collection.js";
+import { RESOURCE_TYPES } from "./package-resource-discovery.js";
+import { buildNoMatchingPackageMessage, dedupePackages, getBaseDirForScope, getPackageIdentity, getPackageSourceString, getSourceMatchKeyForInput, getSourceMatchKeyForSettings, normalizePackageSourceForSettings, parseSource, resolvePath, resolvePathFromBase, } from "./package-source.js";
+export { getPackageTempFolder } from "./package-install-host.js";
+const NETWORK_TIMEOUT_MS = 10000;
+const UPDATE_CHECK_CONCURRENCY = 4;
+const GIT_UPDATE_CONCURRENCY = 4;
+export class DefaultPackageManager {
+    cwd;
+    agentDir;
+    settingsManager;
+    globalNpmRoot;
+    globalNpmRootCommandKey;
+    progressCallback;
+    constructor(options) {
+        this.cwd = resolvePathWithBase(options.cwd);
+        this.agentDir = resolvePathWithBase(options.agentDir);
+        this.settingsManager = options.settingsManager;
+    }
+    get context() {
+        return { cwd: this.cwd, agentDir: this.agentDir, settingsManager: this.settingsManager };
+    }
+    setProgressCallback(callback) {
+        this.progressCallback = callback;
+    }
+    addSourceToSettings(source, options) {
+        const scope = options?.local ? "project" : "user";
+        const currentSettings = scope === "project" ? this.settingsManager.getProjectSettings() : this.settingsManager.getGlobalSettings();
+        const currentPackages = currentSettings.packages ?? [];
+        const normalizedSource = this.normalizePackageSourceForSettings(source, scope);
+        const matchIndex = currentPackages.findIndex((existing) => this.packageSourcesMatch(existing, source, scope));
+        if (matchIndex !== -1) {
+            const existing = currentPackages[matchIndex];
+            if (this.getPackageSourceString(existing) === normalizedSource) {
+                return false;
+            }
+            const nextPackages = [...currentPackages];
+            nextPackages[matchIndex] =
+                typeof existing === "string" ? normalizedSource : { ...existing, source: normalizedSource };
+            if (scope === "project") {
+                this.settingsManager.setProjectPackages(nextPackages);
+            }
+            else {
+                this.settingsManager.setPackages(nextPackages);
+            }
+            return true;
+        }
+        const nextPackages = [...currentPackages, normalizedSource];
+        if (scope === "project") {
+            this.settingsManager.setProjectPackages(nextPackages);
+        }
+        else {
+            this.settingsManager.setPackages(nextPackages);
+        }
+        return true;
+    }
+    removeSourceFromSettings(source, options) {
+        const scope = options?.local ? "project" : "user";
+        const currentSettings = scope === "project" ? this.settingsManager.getProjectSettings() : this.settingsManager.getGlobalSettings();
+        const currentPackages = currentSettings.packages ?? [];
+        const nextPackages = currentPackages.filter((existing) => !this.packageSourcesMatch(existing, source, scope));
+        const changed = nextPackages.length !== currentPackages.length;
+        if (!changed) {
+            return false;
+        }
+        if (scope === "project") {
+            this.settingsManager.setProjectPackages(nextPackages);
+        }
+        else {
+            this.settingsManager.setPackages(nextPackages);
+        }
+        return true;
+    }
+    getInstalledPath(source, scope) {
+        const parsed = this.parseSource(source);
+        if (parsed.type === "npm") {
+            const path = this.getNpmInstallPath(parsed, scope);
+            return existsSync(path) ? path : undefined;
+        }
+        if (parsed.type === "git") {
+            const path = this.getGitInstallPath(parsed, scope);
+            return existsSync(path) ? path : undefined;
+        }
+        if (parsed.type === "local") {
+            const baseDir = this.getBaseDirForScope(scope);
+            const path = this.resolvePathFromBase(parsed.path, baseDir);
+            return existsSync(path) ? path : undefined;
+        }
+        return undefined;
+    }
+    emitProgress(event) {
+        this.progressCallback?.(event);
+    }
+    async withProgress(action, source, message, operation) {
+        this.emitProgress({ type: "start", action, source, message });
+        try {
+            await operation();
+            this.emitProgress({ type: "complete", action, source });
+        }
+        catch (error) {
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            this.emitProgress({ type: "error", action, source, message: errorMessage });
+            throw error;
+        }
+    }
+    async resolve(onMissing) {
+        const accumulator = createAccumulator();
+        const globalSettings = this.settingsManager.getGlobalSettings();
+        const projectSettings = this.settingsManager.getProjectSettings();
+        // Collect all packages with scope (project first so cwd resources win collisions)
+        const allPackages = [];
+        for (const pkg of projectSettings.packages ?? []) {
+            allPackages.push({ pkg, scope: "project" });
+        }
+        for (const pkg of globalSettings.packages ?? []) {
+            allPackages.push({ pkg, scope: "user" });
+        }
+        // Dedupe: project scope wins over global for same package identity
+        const packageSources = this.dedupePackages(allPackages);
+        await this.resolvePackageSources(packageSources, accumulator, onMissing);
+        const globalBaseDir = this.agentDir;
+        const projectBaseDir = join(this.cwd, CONFIG_DIR_NAME);
+        for (const resourceType of RESOURCE_TYPES) {
+            const target = getTargetMap(accumulator, resourceType);
+            const globalEntries = (globalSettings[resourceType] ?? []);
+            const projectEntries = (projectSettings[resourceType] ?? []);
+            resolveLocalEntries(projectEntries, resourceType, target, {
+                source: "local",
+                scope: "project",
+                origin: "top-level",
+            }, projectBaseDir);
+            resolveLocalEntries(globalEntries, resourceType, target, {
+                source: "local",
+                scope: "user",
+                origin: "top-level",
+            }, globalBaseDir);
+        }
+        addAutoDiscoveredResources(this.cwd, accumulator, globalSettings, projectSettings, globalBaseDir, projectBaseDir);
+        return toResolvedPaths(accumulator);
+    }
+    async resolveSourceResources(sources, options) {
+        const accumulator = createAccumulator();
+        const scope = options?.temporary ? "temporary" : options?.local ? "project" : "user";
+        const packageSources = sources.map((source) => ({ pkg: source, scope }));
+        await this.resolvePackageSources(packageSources, accumulator);
+        return toResolvedPaths(accumulator);
+    }
+    listConfiguredPackages() {
+        const globalSettings = this.settingsManager.getGlobalSettings();
+        const projectSettings = this.settingsManager.getProjectSettings();
+        const configuredPackages = [];
+        for (const pkg of globalSettings.packages ?? []) {
+            const source = typeof pkg === "string" ? pkg : pkg.source;
+            configuredPackages.push({
+                source,
+                scope: "user",
+                filtered: typeof pkg === "object",
+                installedPath: this.getInstalledPath(source, "user"),
+            });
+        }
+        for (const pkg of projectSettings.packages ?? []) {
+            const source = typeof pkg === "string" ? pkg : pkg.source;
+            configuredPackages.push({
+                source,
+                scope: "project",
+                filtered: typeof pkg === "object",
+                installedPath: this.getInstalledPath(source, "project"),
+            });
+        }
+        return configuredPackages;
+    }
+    async install(source, options) {
+        const parsed = this.parseSource(source);
+        const scope = options?.local ? "project" : "user";
+        await this.withProgress("install", source, `Installing ${source}...`, async () => {
+            if (parsed.type === "npm") {
+                await this.installNpm(parsed, scope, false);
+                return;
+            }
+            if (parsed.type === "git") {
+                await this.installGit(parsed, scope);
+                return;
+            }
+            if (parsed.type === "local") {
+                const resolved = this.resolvePath(parsed.path);
+                if (!existsSync(resolved)) {
+                    throw new Error(`Path does not exist: ${resolved}`);
+                }
+                return;
+            }
+            throw new Error(`Unsupported install source: ${source}`);
+        });
+    }
+    async installAndPersist(source, options) {
+        await this.install(source, options);
+        this.addSourceToSettings(source, options);
+    }
+    async remove(source, options) {
+        const parsed = this.parseSource(source);
+        const scope = options?.local ? "project" : "user";
+        await this.withProgress("remove", source, `Removing ${source}...`, async () => {
+            if (parsed.type === "npm") {
+                await this.uninstallNpm(parsed, scope);
+                return;
+            }
+            if (parsed.type === "git") {
+                await this.removeGit(parsed, scope);
+                return;
+            }
+            if (parsed.type === "local") {
+                return;
+            }
+            throw new Error(`Unsupported remove source: ${source}`);
+        });
+    }
+    async removeAndPersist(source, options) {
+        await this.remove(source, options);
+        return this.removeSourceFromSettings(source, options);
+    }
+    async update(source) {
+        const globalSettings = this.settingsManager.getGlobalSettings();
+        const projectSettings = this.settingsManager.getProjectSettings();
+        const identity = source ? this.getPackageIdentity(source) : undefined;
+        let matched = false;
+        const updateSources = [];
+        for (const pkg of globalSettings.packages ?? []) {
+            const sourceStr = typeof pkg === "string" ? pkg : pkg.source;
+            if (identity && this.getPackageIdentity(sourceStr, "user") !== identity)
+                continue;
+            matched = true;
+            updateSources.push({ source: sourceStr, scope: "user" });
+        }
+        for (const pkg of projectSettings.packages ?? []) {
+            const sourceStr = typeof pkg === "string" ? pkg : pkg.source;
+            if (identity && this.getPackageIdentity(sourceStr, "project") !== identity)
+                continue;
+            matched = true;
+            updateSources.push({ source: sourceStr, scope: "project" });
+        }
+        if (source && !matched) {
+            throw new Error(this.buildNoMatchingPackageMessage(source, [
+                ...(globalSettings.packages ?? []),
+                ...(projectSettings.packages ?? []),
+            ]));
+        }
+        await this.updateConfiguredSources(updateSources);
+    }
+    async updateConfiguredSources(sources) {
+        if (isOfflineModeEnabled() || sources.length === 0) {
+            return;
+        }
+        const npmCandidates = [];
+        const gitCandidates = [];
+        for (const entry of sources) {
+            const parsed = this.parseSource(entry.source);
+            // Pinned npm versions are fixed. Pinned git refs are configured checkout targets,
+            // so include them to reconcile an existing clone when the configured ref changes.
+            if (parsed.type === "npm") {
+                if (!parsed.pinned) {
+                    npmCandidates.push({ ...entry, parsed });
+                }
+            }
+            else if (parsed.type === "git") {
+                gitCandidates.push({ ...entry, parsed });
+            }
+        }
+        const npmCheckTasks = npmCandidates.map((entry) => async () => ({
+            entry,
+            shouldUpdate: await this.shouldUpdateNpmSource(entry.parsed, entry.scope),
+        }));
+        const npmCheckResults = await runWithConcurrency(npmCheckTasks, UPDATE_CHECK_CONCURRENCY);
+        const userNpmUpdates = [];
+        const projectNpmUpdates = [];
+        for (const result of npmCheckResults) {
+            if (!result.shouldUpdate) {
+                continue;
+            }
+            if (result.entry.scope === "user") {
+                userNpmUpdates.push(result.entry);
+            }
+            else {
+                projectNpmUpdates.push(result.entry);
+            }
+        }
+        const tasks = [];
+        if (userNpmUpdates.length > 0) {
+            tasks.push(this.updateNpmBatch(userNpmUpdates, "user"));
+        }
+        if (projectNpmUpdates.length > 0) {
+            tasks.push(this.updateNpmBatch(projectNpmUpdates, "project"));
+        }
+        if (gitCandidates.length > 0) {
+            const gitTasks = gitCandidates.map((entry) => async () => this.withProgress("update", entry.source, `Updating ${entry.source}...`, async () => {
+                await this.updateGit(entry.parsed, entry.scope);
+            }));
+            tasks.push(runWithConcurrency(gitTasks, GIT_UPDATE_CONCURRENCY).then(() => { }));
+        }
+        await Promise.all(tasks);
+    }
+    async shouldUpdateNpmSource(source, scope) {
+        const installedPath = getManagedNpmInstallPath(this.context, source, scope);
+        const installedVersion = existsSync(installedPath) ? this.getInstalledNpmVersion(installedPath) : undefined;
+        if (!installedVersion) {
+            return true;
+        }
+        const targetVersion = await this.getLatestNpmVersion(source.version ? source.spec : source.name, source.range);
+        return gt(targetVersion, installedVersion);
+    }
+    async updateNpmBatch(sources, scope) {
+        if (sources.length === 0) {
+            return;
+        }
+        const sourceLabel = sources.length === 1 ? sources[0].source : `${scope} npm packages`;
+        const message = sources.length === 1 ? `Updating ${sources[0].source}...` : `Updating ${scope} npm packages...`;
+        const specs = sources.map((entry) => (entry.parsed.version ? entry.parsed.spec : `${entry.parsed.name}@latest`));
+        await this.withProgress("update", sourceLabel, message, async () => {
+            await this.installNpmBatch(specs, scope);
+        });
+    }
+    async installNpmBatch(specs, scope) {
+        const installRoot = getNpmInstallRoot(this.context, scope, false);
+        ensureNpmProject(installRoot);
+        await this.runNpmCommand(getNpmInstallArgs(this.context, specs, installRoot));
+    }
+    async checkForAvailableUpdates() {
+        if (isOfflineModeEnabled()) {
+            return [];
+        }
+        const globalSettings = this.settingsManager.getGlobalSettings();
+        const projectSettings = this.settingsManager.getProjectSettings();
+        const allPackages = [];
+        for (const pkg of projectSettings.packages ?? []) {
+            allPackages.push({ pkg, scope: "project" });
+        }
+        for (const pkg of globalSettings.packages ?? []) {
+            allPackages.push({ pkg, scope: "user" });
+        }
+        const packageSources = this.dedupePackages(allPackages);
+        const checks = packageSources
+            .filter((entry) => entry.scope !== "temporary")
+            .map((entry) => async () => {
+            const source = typeof entry.pkg === "string" ? entry.pkg : entry.pkg.source;
+            const parsed = this.parseSource(source);
+            if (parsed.type === "local" || parsed.pinned) {
+                return undefined;
+            }
+            if (parsed.type === "npm") {
+                const installedPath = this.getNpmInstallPath(parsed, entry.scope);
+                if (!existsSync(installedPath)) {
+                    return undefined;
+                }
+                const hasUpdate = await this.npmHasAvailableUpdate(parsed, installedPath);
+                if (!hasUpdate) {
+                    return undefined;
+                }
+                return {
+                    source,
+                    displayName: parsed.name,
+                    type: "npm",
+                    scope: entry.scope,
+                };
+            }
+            const installedPath = this.getGitInstallPath(parsed, entry.scope);
+            if (!existsSync(installedPath)) {
+                return undefined;
+            }
+            const hasUpdate = await this.gitHasAvailableUpdate(installedPath);
+            if (!hasUpdate) {
+                return undefined;
+            }
+            return {
+                source,
+                displayName: `${parsed.host}/${parsed.path}`,
+                type: "git",
+                scope: entry.scope,
+            };
+        });
+        const results = await runWithConcurrency(checks, UPDATE_CHECK_CONCURRENCY);
+        return results.filter((result) => result !== undefined);
+    }
+    async resolvePackageSources(sources, accumulator, onMissing) {
+        for (const { pkg, scope } of sources) {
+            const sourceStr = typeof pkg === "string" ? pkg : pkg.source;
+            const filter = typeof pkg === "object" ? pkg : undefined;
+            const deltaBase = this.findAutoloadDeltaBase(pkg, scope, sources);
+            const resolvedSource = deltaBase?.source ?? sourceStr;
+            const resolvedScope = deltaBase?.scope ?? scope;
+            const parsed = this.parseSource(resolvedSource);
+            const metadata = { source: sourceStr, scope, origin: "package" };
+            if (parsed.type === "local") {
+                const baseDir = this.getBaseDirForScope(resolvedScope);
+                const resolvedLocal = this.resolvePathFromBase(parsed.path, baseDir);
+                if (existsSync(resolvedLocal)) {
+                    try {
+                        if (statSync(resolvedLocal).isDirectory()) {
+                            metadata.baseDir = resolvedLocal;
+                            collectPackageResources(resolvedLocal, accumulator, filter, metadata);
+                        }
+                    }
+                    catch {
+                        // Unreadable local path: skip the source.
+                    }
+                }
+                continue;
+            }
+            const installMissing = async () => {
+                if (isOfflineModeEnabled())
+                    return false;
+                if (!onMissing) {
+                    await this.installParsedSource(parsed, resolvedScope);
+                    return true;
+                }
+                const action = await onMissing(resolvedSource);
+                if (action === "skip")
+                    return false;
+                if (action === "error")
+                    throw new Error(`Missing source: ${resolvedSource}`);
+                await this.installParsedSource(parsed, resolvedScope);
+                return true;
+            };
+            if (parsed.type === "npm") {
+                let installedPath = this.getNpmInstallPath(parsed, resolvedScope);
+                const needsInstall = !existsSync(installedPath) || !(await installedNpmMatchesConfiguredVersion(parsed, installedPath));
+                if (needsInstall) {
+                    const installed = await installMissing();
+                    if (!installed)
+                        continue;
+                    installedPath = this.getNpmInstallPath(parsed, resolvedScope);
+                }
+                metadata.baseDir = installedPath;
+                collectPackageResources(installedPath, accumulator, filter, metadata);
+                continue;
+            }
+            if (parsed.type === "git") {
+                const installedPath = this.getGitInstallPath(parsed, resolvedScope);
+                if (!existsSync(installedPath)) {
+                    const installed = await installMissing();
+                    if (!installed)
+                        continue;
+                }
+                else if (resolvedScope === "temporary" && !parsed.pinned && !isOfflineModeEnabled()) {
+                    await this.refreshTemporaryGitSource(parsed, resolvedSource);
+                }
+                metadata.baseDir = installedPath;
+                collectPackageResources(installedPath, accumulator, filter, metadata);
+            }
+        }
+    }
+    findAutoloadDeltaBase(pkg, scope, sources) {
+        if (scope !== "project" || typeof pkg !== "object" || pkg.autoload !== false)
+            return undefined;
+        const identity = this.getPackageIdentity(pkg.source, scope);
+        const userEntry = sources.find((entry) => entry.scope === "user" &&
+            this.getPackageIdentity(this.getPackageSourceString(entry.pkg), "user") === identity);
+        return userEntry ? { source: this.getPackageSourceString(userEntry.pkg), scope: "user" } : undefined;
+    }
+    async installParsedSource(parsed, scope) {
+        if (parsed.type === "npm") {
+            await this.installNpm(parsed, scope, scope === "temporary");
+            return;
+        }
+        if (parsed.type === "git") {
+            await this.installGit(parsed, scope);
+            return;
+        }
+    }
+    parseSource(source) {
+        return parseSource(source);
+    }
+    getBaseDirForScope(scope) {
+        return getBaseDirForScope(this.context, scope);
+    }
+    resolvePath(input) {
+        return resolvePath(this.context, input);
+    }
+    resolvePathFromBase(input, baseDir) {
+        return resolvePathFromBase(input, baseDir);
+    }
+    getPackageSourceString(pkg) {
+        return getPackageSourceString(pkg);
+    }
+    getSourceMatchKeyForInput(source) {
+        return getSourceMatchKeyForInput(this.context, source);
+    }
+    getSourceMatchKeyForSettings(source, scope) {
+        return getSourceMatchKeyForSettings(this.context, source, scope);
+    }
+    packageSourcesMatch(existing, inputSource, scope) {
+        const left = this.getSourceMatchKeyForSettings(this.getPackageSourceString(existing), scope);
+        const right = this.getSourceMatchKeyForInput(inputSource);
+        return left === right;
+    }
+    normalizePackageSourceForSettings(source, scope) {
+        return normalizePackageSourceForSettings(this.context, source, scope);
+    }
+    getPackageIdentity(source, scope) {
+        return getPackageIdentity(this.context, source, scope);
+    }
+    dedupePackages(packages) {
+        return dedupePackages(this.context, packages);
+    }
+    buildNoMatchingPackageMessage(source, configuredPackages) {
+        return buildNoMatchingPackageMessage(source, configuredPackages);
+    }
+    getNpmCommand() {
+        return getNpmCommand(this.context);
+    }
+    getInstalledNpmVersion(installedPath) {
+        return getInstalledNpmVersion(installedPath);
+    }
+    getGitInstallPath(source, scope) {
+        return getGitInstallPath(this.context, source, scope);
+    }
+    async npmHasAvailableUpdate(source, installedPath) {
+        if (isOfflineModeEnabled()) {
+            return false;
+        }
+        const installedVersion = this.getInstalledNpmVersion(installedPath);
+        if (!installedVersion) {
+            return false;
+        }
+        try {
+            const targetVersion = await this.getLatestNpmVersion(source.version ? source.spec : source.name, source.range);
+            return gt(targetVersion, installedVersion);
+        }
+        catch {
+            return false;
+        }
+    }
+    async getLatestNpmVersion(packageSpec, range) {
+        const npmCommand = this.getNpmCommand();
+        const stdout = await this.runCommandCapture(npmCommand.command, [...npmCommand.args, "view", packageSpec, "version", "--json"], { cwd: this.cwd, timeoutMs: NETWORK_TIMEOUT_MS });
+        const raw = stdout.trim();
+        if (!raw)
+            throw new Error("Empty response from npm view");
+        const parsed = JSON.parse(raw);
+        if (typeof parsed === "string") {
+            return parsed;
+        }
+        if (Array.isArray(parsed)) {
+            const versions = parsed.filter((value) => typeof value === "string" && value.length > 0);
+            const latest = range ? maxSatisfying(versions, range) : [...versions].sort(rcompare)[0];
+            if (latest)
+                return latest;
+        }
+        throw new Error("Unexpected response from npm view");
+    }
+    async gitHasAvailableUpdate(installedPath) {
+        if (isOfflineModeEnabled()) {
+            return false;
+        }
+        try {
+            const localHead = await this.runCommandCapture("git", ["rev-parse", "HEAD"], {
+                cwd: installedPath,
+                timeoutMs: NETWORK_TIMEOUT_MS,
+            });
+            const remoteHead = await this.getRemoteGitHead(installedPath);
+            return localHead.trim() !== remoteHead.trim();
+        }
+        catch {
+            return false;
+        }
+    }
+    async getRemoteGitHead(installedPath) {
+        const upstreamRef = await this.getGitUpstreamRef(installedPath);
+        if (upstreamRef) {
+            const remoteHead = await this.runGitRemoteCommand(installedPath, ["ls-remote", "origin", upstreamRef]);
+            const match = remoteHead.match(/^([0-9a-f]{40})\s+/m);
+            if (match?.[1]) {
+                return match[1];
+            }
+        }
+        const remoteHead = await this.runGitRemoteCommand(installedPath, ["ls-remote", "origin", "HEAD"]);
+        const match = remoteHead.match(/^([0-9a-f]{40})\s+HEAD$/m);
+        if (!match?.[1]) {
+            throw new Error("Failed to determine remote HEAD");
+        }
+        return match[1];
+    }
+    async getLocalGitUpdateTarget(installedPath) {
+        try {
+            const upstream = await this.runCommandCapture("git", ["rev-parse", "--abbrev-ref", "@{upstream}"], {
+                cwd: installedPath,
+                timeoutMs: NETWORK_TIMEOUT_MS,
+            });
+            const trimmedUpstream = upstream.trim();
+            if (!trimmedUpstream.startsWith("origin/")) {
+                throw new Error(`Unsupported upstream remote: ${trimmedUpstream}`);
+            }
+            const branch = trimmedUpstream.slice("origin/".length);
+            if (!branch) {
+                throw new Error("Missing upstream branch name");
+            }
+            const head = await this.runCommandCapture("git", ["rev-parse", "@{upstream}"], {
+                cwd: installedPath,
+                timeoutMs: NETWORK_TIMEOUT_MS,
+            });
+            return {
+                ref: "@{upstream}",
+                head,
+                fetchArgs: [
+                    "fetch",
+                    "--prune",
+                    "--no-tags",
+                    "origin",
+                    `+refs/heads/${branch}:refs/remotes/origin/${branch}`,
+                ],
+            };
+        }
+        catch {
+            await this.runCommand("git", ["remote", "set-head", "origin", "-a"], { cwd: installedPath }).catch(() => { });
+            const head = await this.runCommandCapture("git", ["rev-parse", "origin/HEAD"], {
+                cwd: installedPath,
+                timeoutMs: NETWORK_TIMEOUT_MS,
+            });
+            const originHeadRef = await this.runCommandCapture("git", ["symbolic-ref", "refs/remotes/origin/HEAD"], {
+                cwd: installedPath,
+                timeoutMs: NETWORK_TIMEOUT_MS,
+            }).catch(() => "");
+            const branch = originHeadRef.trim().replace(/^refs\/remotes\/origin\//, "");
+            if (branch) {
+                return {
+                    ref: "origin/HEAD",
+                    head,
+                    fetchArgs: [
+                        "fetch",
+                        "--prune",
+                        "--no-tags",
+                        "origin",
+                        `+refs/heads/${branch}:refs/remotes/origin/${branch}`,
+                    ],
+                };
+            }
+            return {
+                ref: "origin/HEAD",
+                head,
+                fetchArgs: ["fetch", "--prune", "--no-tags", "origin", "+HEAD:refs/remotes/origin/HEAD"],
+            };
+        }
+    }
+    async getGitUpstreamRef(installedPath) {
+        try {
+            const upstream = await this.runCommandCapture("git", ["rev-parse", "--abbrev-ref", "@{upstream}"], {
+                cwd: installedPath,
+                timeoutMs: NETWORK_TIMEOUT_MS,
+            });
+            const trimmed = upstream.trim();
+            if (!trimmed.startsWith("origin/")) {
+                return undefined;
+            }
+            const branch = trimmed.slice("origin/".length);
+            return branch ? `refs/heads/${branch}` : undefined;
+        }
+        catch {
+            return undefined;
+        }
+    }
+    runGitRemoteCommand(installedPath, args) {
+        return this.runCommandCapture("git", args, {
+            cwd: installedPath,
+            timeoutMs: NETWORK_TIMEOUT_MS,
+            env: {
+                GIT_TERMINAL_PROMPT: "0",
+            },
+        });
+    }
+    getGlobalNpmRoot() {
+        const npmCommand = this.getNpmCommand();
+        const commandKey = [npmCommand.command, ...npmCommand.args].join("\0");
+        if (this.globalNpmRoot && this.globalNpmRootCommandKey === commandKey) {
+            return this.globalNpmRoot;
+        }
+        if (getPackageManagerName(this.context) === "bun") {
+            const binDir = this.runNpmCommandSync(["pm", "bin", "-g"]).trim();
+            this.globalNpmRoot = join(dirname(binDir), "install", "global", "node_modules");
+        }
+        else {
+            this.globalNpmRoot = this.runNpmCommandSync(["root", "-g"]).trim();
+        }
+        this.globalNpmRootCommandKey = commandKey;
+        return this.globalNpmRoot;
+    }
+    getPnpmGlobalPackagePath(packageName) {
+        if (getPackageManagerName(this.context) !== "pnpm") {
+            return undefined;
+        }
+        const output = this.runNpmCommandSync(["list", "-g", "--depth", "0", "--json"]);
+        const entries = JSON.parse(output);
+        for (const entry of entries) {
+            const path = entry.dependencies?.[packageName]?.path;
+            if (path)
+                return path;
+        }
+        return undefined;
+    }
+    getLegacyGlobalNpmInstallPath(source) {
+        // Read-only migration compatibility for pre-managed global installs. New installs
+        // always target the Agent Forge-managed root; this lookup never substitutes a package.
+        try {
+            return this.getPnpmGlobalPackagePath(source.name) ?? join(this.getGlobalNpmRoot(), source.name);
+        }
+        catch {
+            return undefined;
+        }
+    }
+    getNpmInstallPath(source, scope) {
+        const managedPath = getManagedNpmInstallPath(this.context, source, scope);
+        if (scope !== "user" || existsSync(managedPath)) {
+            return managedPath;
+        }
+        const legacyPath = this.getLegacyGlobalNpmInstallPath(source);
+        return legacyPath && existsSync(legacyPath) ? legacyPath : managedPath;
+    }
+    async installNpm(source, scope, temporary) {
+        const installRoot = getNpmInstallRoot(this.context, scope, temporary);
+        ensureNpmProject(installRoot);
+        await this.runNpmCommand(getNpmInstallArgs(this.context, [source.spec], installRoot));
+    }
+    async uninstallNpm(source, scope) {
+        const installRoot = getNpmInstallRoot(this.context, scope, false);
+        if (!existsSync(installRoot)) {
+            return;
+        }
+        const packageManagerName = getPackageManagerName(this.context);
+        if (packageManagerName === "bun") {
+            await this.runNpmCommand(["uninstall", source.name, "--cwd", installRoot]);
+            return;
+        }
+        const args = ["uninstall", source.name, "--prefix", installRoot];
+        if (packageManagerName !== "pnpm") {
+            args.push("--legacy-peer-deps");
+        }
+        await this.runNpmCommand(args);
+    }
+    async installGit(source, scope) {
+        const targetDir = this.getGitInstallPath(source, scope);
+        if (existsSync(targetDir)) {
+            if (source.ref) {
+                await this.ensureGitRef(targetDir, ["fetch", "origin", source.ref], "FETCH_HEAD");
+                return;
+            }
+            const target = await this.getLocalGitUpdateTarget(targetDir);
+            await this.ensureGitRef(targetDir, target.fetchArgs, target.ref);
+            return;
+        }
+        const gitRoot = getGitInstallRoot(this.context, scope);
+        if (gitRoot) {
+            ensureGitIgnore(gitRoot);
+        }
+        mkdirSync(dirname(targetDir), { recursive: true });
+        rmSync(getGitUpdateMarkerPath(targetDir), { force: true });
+        try {
+            await this.runCommand("git", ["clone", source.repo, targetDir]);
+            if (source.ref) {
+                await this.runCommand("git", ["checkout", source.ref], { cwd: targetDir });
+            }
+            const packageJsonPath = join(targetDir, "package.json");
+            if (existsSync(packageJsonPath)) {
+                await this.runNpmCommand(getGitDependencyInstallArgs(this.context), { cwd: targetDir });
+            }
+        }
+        catch (error) {
+            rmSync(targetDir, { recursive: true, force: true });
+            pruneEmptyGitParents(targetDir, gitRoot);
+            throw error;
+        }
+    }
+    async updateGit(source, scope) {
+        const targetDir = this.getGitInstallPath(source, scope);
+        if (!existsSync(targetDir)) {
+            await this.installGit(source, scope);
+            return;
+        }
+        if (source.ref) {
+            await this.ensureGitRef(targetDir, ["fetch", "origin", source.ref], "FETCH_HEAD");
+            return;
+        }
+        const target = await this.getLocalGitUpdateTarget(targetDir);
+        await this.ensureGitRef(targetDir, target.fetchArgs, target.ref);
+    }
+    async repairMissingGitDependencies(targetDir) {
+        if (!hasMissingGitDependencies(targetDir))
+            return;
+        await this.runNpmCommand(getGitDependencyInstallArgs(this.context), { cwd: targetDir });
+    }
+    async cleanAndInstallGitDependencies(targetDir, markerPath) {
+        // Clean untracked files (extensions should be pristine). If this fails after
+        // deleting dependencies, repair them so the existing extension still loads.
+        try {
+            await this.runCommand("git", ["clean", "-fdx"], { cwd: targetDir });
+        }
+        catch (error) {
+            await this.repairMissingGitDependencies(targetDir).catch(() => { });
+            throw error;
+        }
+        const packageJsonPath = join(targetDir, "package.json");
+        if (existsSync(packageJsonPath)) {
+            await this.runNpmCommand(getGitDependencyInstallArgs(this.context), { cwd: targetDir });
+        }
+        rmSync(markerPath, { force: true });
+    }
+    async ensureGitRef(targetDir, fetchArgs, ref) {
+        // Fetch only the ref we will reset to, avoiding unrelated branch/tag noise.
+        await this.runCommand("git", fetchArgs, { cwd: targetDir });
+        const localHead = await this.runCommandCapture("git", ["rev-parse", "HEAD"], {
+            cwd: targetDir,
+            timeoutMs: NETWORK_TIMEOUT_MS,
+        });
+        const commitRef = `${ref}^{commit}`;
+        const targetHead = await this.runCommandCapture("git", ["rev-parse", commitRef], {
+            cwd: targetDir,
+            timeoutMs: NETWORK_TIMEOUT_MS,
+        });
+        const markerPath = getGitUpdateMarkerPath(targetDir);
+        if (localHead.trim() === targetHead.trim()) {
+            if (existsSync(markerPath)) {
+                await this.cleanAndInstallGitDependencies(targetDir, markerPath);
+            }
+            else {
+                await this.repairMissingGitDependencies(targetDir);
+            }
+            return;
+        }
+        writeFileSync(markerPath, "", "utf-8");
+        await this.runCommand("git", ["reset", "--hard", commitRef], { cwd: targetDir });
+        await this.cleanAndInstallGitDependencies(targetDir, markerPath);
+    }
+    async refreshTemporaryGitSource(source, sourceStr) {
+        if (isOfflineModeEnabled()) {
+            return;
+        }
+        try {
+            await this.withProgress("pull", sourceStr, `Refreshing ${sourceStr}...`, async () => {
+                await this.updateGit(source, "temporary");
+            });
+        }
+        catch {
+            // Keep cached temporary checkout if refresh fails.
+        }
+    }
+    async removeGit(source, scope) {
+        const targetDir = this.getGitInstallPath(source, scope);
+        rmSync(targetDir, { recursive: true, force: true });
+        rmSync(getGitUpdateMarkerPath(targetDir), { force: true });
+        pruneEmptyGitParents(targetDir, getGitInstallRoot(this.context, scope));
+    }
+    async runNpmCommand(args, options) {
+        const npmCommand = this.getNpmCommand();
+        await this.runCommand(npmCommand.command, [...npmCommand.args, ...args], options);
+    }
+    runNpmCommandSync(args) {
+        const npmCommand = this.getNpmCommand();
+        return this.runCommandSync(npmCommand.command, [...npmCommand.args, ...args]);
+    }
+    spawnCommand(command, args, options) {
+        const env = getEnv();
+        return spawnProcess(command, args, {
+            cwd: options?.cwd,
+            stdio: isStdoutTakenOver() ? ["ignore", 2, 2] : "inherit",
+            env,
+        });
+    }
+    spawnCaptureCommand(command, args, options) {
+        const baseEnv = getEnv();
+        const env = options?.env ? { ...baseEnv, ...options.env } : baseEnv;
+        return spawnProcess(command, args, {
+            cwd: options?.cwd,
+            stdio: ["ignore", "pipe", "pipe"],
+            env,
+        });
+    }
+    runCommandCapture(command, args, options) {
+        return new Promise((resolvePromise, reject) => {
+            const child = this.spawnCaptureCommand(command, args, options);
+            let stdout = "";
+            let stderr = "";
+            let timedOut = false;
+            const timeout = typeof options?.timeoutMs === "number"
+                ? setTimeout(() => {
+                    timedOut = true;
+                    child.kill();
+                }, options.timeoutMs)
+                : undefined;
+            child.stdout?.on("data", (data) => {
+                stdout += data.toString();
+            });
+            child.stderr?.on("data", (data) => {
+                stderr += data.toString();
+            });
+            child.once("error", (error) => {
+                if (timeout)
+                    clearTimeout(timeout);
+                reject(error);
+            });
+            child.once("close", (code, signal) => {
+                if (timeout)
+                    clearTimeout(timeout);
+                if (timedOut) {
+                    reject(new Error(`${command} ${args.join(" ")} timed out after ${options?.timeoutMs}ms`));
+                    return;
+                }
+                if (code === 0) {
+                    resolvePromise(stdout.trim());
+                    return;
+                }
+                const exitStatus = code === null ? `signal ${signal ?? "unknown"}` : `code ${code}`;
+                reject(new Error(`${command} ${args.join(" ")} failed with ${exitStatus}: ${stderr || stdout}`));
+            });
+        });
+    }
+    runCommand(command, args, options) {
+        return new Promise((resolvePromise, reject) => {
+            const child = this.spawnCommand(command, args, options);
+            child.on("error", reject);
+            child.on("exit", (code) => {
+                if (code === 0) {
+                    resolvePromise();
+                }
+                else {
+                    reject(new Error(`${command} ${args.join(" ")} failed with code ${code}`));
+                }
+            });
+        });
+    }
+    runCommandSync(command, args) {
+        const env = getEnv();
+        const result = spawnProcessSync(command, args, {
+            stdio: ["ignore", "pipe", "pipe"],
+            encoding: "utf-8",
+            env,
+        });
+        if (result.error || result.status !== 0) {
+            throw new Error(`Failed to run ${command} ${args.join(" ")}: ${result.error?.message || result.stderr || result.stdout}`);
+        }
+        return (result.stdout || result.stderr || "").trim();
+    }
+}
+//# sourceMappingURL=package-manager.js.map