@hagicode/hagiscript 0.1.15-dev.91.1.7ddec89 → 0.1.15-dev.94.1.64ce9f6

package/dist/runtime/server-manager.js

@@ -1,16 +1,18 @@
-import { cp, mkdtemp, mkdir, readdir, rm, stat, writeFile } from "node:fs/promises";
+import { cp, mkdtemp, mkdir, readFile, readdir, rm, stat, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
-import { basename, join, resolve } from "node:path";
+import { basename, dirname, join, resolve } from "node:path";
 import { createHash } from "node:crypto";
 import process from "node:process";
 import semver from "semver";
+import { parse as parseYaml } from "yaml";
 import { copyFileFromCache, isDownloadCacheEnabled, resolveDownloadCacheDirectory, storeFileInCache } from "./download-cache.js";
 import { runCommand } from "./command-launch.js";
-import { syncNpmGlobals, validateRegistryMirror } from "./npm-sync.js";
-import { resolveManagedPm2Environment, runManagedPm2Command } from "./pm2-manager.js";
+import { resolveManagedPm2Environment, runManagedPm2Command, supportedPm2Services } from "./pm2-manager.js";
 import { loadRuntimeManifest } from "./runtime-manifest.js";
-import { getComponentManagedRoot, resolveRuntimePaths } from "./runtime-paths.js";
-import { installRuntime, queryRuntimeState } from "./runtime-manager.js";
+import { getComponentConfigDirectory, getServerSharedDataRoot, getServerVersionRoot, resolveRuntimePaths } from "./runtime-paths.js";
+import { ensureManagedPm2Package, installRuntime, queryRuntimeState } from "./runtime-manager.js";
+import { getManagedServerConfig } from "./server-config.js";
+import { listManagedServerVersions as listManagedServerVersionSummaries, readManagedServerVersionState, registerManagedServerVersion, removeManagedServerVersion as removeInstalledManagedServerVersion, resolveManagedServerVersionStateContext, setActiveManagedServerVersion } from "./server-version-state.js";
 export class ManagedServerError extends Error {
     constructor(message, options) {
         super(message, options);
@@ -19,44 +21,75 @@ export class ManagedServerError extends Error {
 }
 const DEFAULT_GITHUB_REPOSITORY = "HagiCode-org/releases";
 const DEFAULT_GITHUB_TAG = "latest";
-const DEFAULT_PM2_INSTANCE = "hagicode";
+const DEFAULT_SERVER_HTTP_INDEX_URL = "https://index.hagicode.com/server/index.json";
+const LEGACY_SERVER_HTTP_INDEX_URLS = new Set([
+    "https://server.dl.hagicode.com/index.json"
+]);
+const DEFAULT_CODE_SERVER_HOST = "127.0.0.1";
+const DEFAULT_CODE_SERVER_PORT = 8080;
+const DEFAULT_CODE_SERVER_AUTH_MODE = "none";
+const DEFAULT_OMNIROUTE_HOST = "127.0.0.1";
+const DEFAULT_OMNIROUTE_PORT = 39001;
+const MANAGED_SERVER_INTEGRATION_DEPENDENCIES = [
+    "code-server",
+    "omniroute"
+];
+const VSCODE_SERVER_SOURCE_EXTERNAL = "external";
+const VSCODE_SERVER_SECRET_SOURCE_BOOTSTRAP = "bootstrap";
+const OMNIROUTE_SOURCE_EXTERNAL = "external";
 export async function installManagedServer(options = {}) {
     const logger = options.logger ?? (() => undefined);
     const runner = options.runner ?? runCommand;
     const manifest = await loadRuntimeManifest({ manifestPath: options.manifestPath });
+    const resolvedInstallOptions = applyManifestServerInstallDefaults(manifest, options);
     const paths = resolveRuntimePaths(manifest, { runtimeRoot: options.runtimeRoot });
     const serverComponent = assertServerComponent(manifest.componentMap.get("server"));
-    const resolvedRegistryMirror = validateRegistryMirror(options.registryMirror, "registryMirror");
-    const archive = await resolveServerArchive(options, logger);
+    const archive = await resolveServerArchive(resolvedInstallOptions, logger);
+    const installedVersion = resolveManagedServerVersion(archive);
     try {
         const staged = await stageServerArchive({
             archivePath: archive.archivePath,
+            version: installedVersion,
             paths,
             runner,
             serverComponent,
+            force: options.force ?? false,
             extractArchive: options.extractArchive
         });
         const installRuntimeFn = options.installRuntimeFn ?? installRuntime;
+        const runtimeDependencyComponents = [...serverComponent.lifecycleDependencies];
         const runtimeLifecycle = await installRuntimeFn({
             manifestPath: options.manifestPath,
             runtimeRoot: options.runtimeRoot,
-            components: ["server"],
+            components: runtimeDependencyComponents,
             force: options.force ?? false,
             downloadCache: options.downloadCache,
             downloadCacheDir: options.downloadCacheDir,
+            npmRegistryMirror: options.registryMirror,
+            pm2VersionOverride: options.pm2Version,
             logger
         });
-        let pm2Summary;
         if (options.ensurePm2 ?? true) {
-            pm2Summary = await ensureManagedPm2({
-                paths,
-                pm2Version: options.pm2Version,
-                registryMirror: resolvedRegistryMirror,
-                force: options.force ?? false,
-                logger,
-                syncNpmGlobalsFn: options.syncNpmGlobalsFn
+            await ensureManagedPm2Package(manifest, paths, {
+                npmRegistryMirror: options.registryMirror,
+                pm2VersionOverride: options.pm2Version
             });
         }
+        const versionStateContext = await resolveManagedServerVersionStateContext({
+            manifestPath: options.manifestPath,
+            runtimeRoot: options.runtimeRoot
+        });
+        const sharedDataRoot = getServerSharedDataRoot(versionStateContext.paths);
+        await registerManagedServerVersion(versionStateContext.statePath, {
+            version: installedVersion,
+            installPath: staged.stagedPath,
+            installedAt: new Date().toISOString(),
+            source: {
+                kind: archive.kind,
+                locator: archive.locator,
+                assetName: archive.assetName
+            }
+        });
         const queryRuntimeStateFn = options.queryRuntimeStateFn ?? queryRuntimeState;
         const runtimeState = await queryRuntimeStateFn({
             manifestPath: options.manifestPath,
@@ -69,14 +102,17 @@ export async function installManagedServer(options = {}) {
                 version: archive.version,
                 assetName: archive.assetName
             },
+            installedVersion,
+            activeVersion: installedVersion,
             stagedPath: staged.stagedPath,
             stagedDllPath: staged.stagedDllPath,
+            statePath: versionStateContext.statePath,
+            sharedDataRoot,
             runtimeLifecycle,
             runtimeState,
             pm2: {
                 ensured: options.ensurePm2 ?? true,
-                versionRange: options.ensurePm2 === false ? null : normalizePm2Version(options.pm2Version),
-                summary: pm2Summary
+                versionRange: options.ensurePm2 === false ? null : normalizePm2Version(options.pm2Version)
             }
         };
     }
@@ -84,9 +120,73 @@ export async function installManagedServer(options = {}) {
         await archive.cleanup();
     }
 }
+function applyManifestServerInstallDefaults(manifest, options) {
+    if (options.archivePath ||
+        options.packageDirectory ||
+        options.url ||
+        options.indexUrl ||
+        options.indexChannel ||
+        options.indexVersion) {
+        return options;
+    }
+    const serverComponent = manifest.componentMap.get("server");
+    const activeVersion = serverComponent?.releasedService?.activeVersion?.trim();
+    if (!activeVersion) {
+        return options;
+    }
+    return {
+        ...options,
+        indexVersion: activeVersion
+    };
+}
 export async function startManagedServer(options = {}) {
     return runManagedServerAction("start", options);
 }
+export async function listManagedServerVersions(options = {}) {
+    const context = await resolveManagedServerVersionStateContext(options);
+    const state = await readManagedServerVersionState(context.statePath);
+    return {
+        activeVersion: state.activeVersion,
+        versions: await listManagedServerVersionSummaries(context.statePath),
+        statePath: context.statePath,
+        sharedDataRoot: getServerSharedDataRoot(context.paths)
+    };
+}
+export async function useManagedServerVersion(options) {
+    const version = options.version.trim();
+    if (!version) {
+        throw new ManagedServerError("Managed server version must be a non-empty string.");
+    }
+    const context = await resolveManagedServerVersionStateContext(options);
+    const state = await readManagedServerVersionState(context.statePath);
+    const previousActiveVersion = state.activeVersion;
+    await setActiveManagedServerVersion(context.statePath, version);
+    return {
+        previousActiveVersion,
+        activeVersion: version,
+        statePath: context.statePath
+    };
+}
+export async function removeManagedServerInstalledVersion(options) {
+    const version = options.version.trim();
+    if (!version) {
+        throw new ManagedServerError("Managed server version must be a non-empty string.");
+    }
+    const context = await resolveManagedServerVersionStateContext(options);
+    const state = await readManagedServerVersionState(context.statePath);
+    const installedVersion = state.versions[version];
+    if (!installedVersion) {
+        throw new ManagedServerError(`Managed server version ${version} is not installed.`);
+    }
+    await rm(installedVersion.installPath, { recursive: true, force: true });
+    const nextState = await removeInstalledManagedServerVersion(context.statePath, version);
+    return {
+        activeVersion: nextState.activeVersion,
+        removedVersion: version,
+        removedPath: installedVersion.installPath,
+        statePath: context.statePath
+    };
+}
 export async function restartManagedServer(options = {}) {
     return runManagedServerAction("restart", options);
 }
@@ -97,27 +197,160 @@ export async function getManagedServerStatus(options = {}) {
     return runManagedServerAction("status", options);
 }
 export async function resolveManagedServerStartupEnvironment(options = {}) {
+    const environmentOverrides = (await resolveManagedServerEnvironment(options)).environment;
     return resolveManagedPm2Environment({
         manifestPath: options.manifestPath,
         runtimeRoot: options.runtimeRoot,
         service: "server",
-        nameIdentifierValue: options.instanceName?.trim() || DEFAULT_PM2_INSTANCE
+        nameIdentifierValue: options.instanceName?.trim(),
+        environmentOverrides
     });
 }
 async function runManagedServerAction(action, options) {
+    if (action === "start") {
+        await ensureManagedServerDependenciesStarted(options);
+    }
+    const environmentOverrides = (await resolveManagedServerEnvironment(options)).environment;
     return runManagedPm2Command({
         manifestPath: options.manifestPath,
         runtimeRoot: options.runtimeRoot,
         service: "server",
         action,
-        nameIdentifierValue: options.instanceName?.trim() || DEFAULT_PM2_INSTANCE
+        nameIdentifierValue: options.instanceName?.trim(),
+        environmentOverrides
+    });
+}
+async function ensureManagedServerDependenciesStarted(options) {
+    const manifest = await loadRuntimeManifest({ manifestPath: options.manifestPath });
+    const managedPm2ServiceNames = new Set(supportedPm2Services);
+    const dependencyServices = MANAGED_SERVER_INTEGRATION_DEPENDENCIES.filter((service) => service !== "server" && managedPm2ServiceNames.has(service) && manifest.componentMap.has(service));
+    for (const service of dependencyServices) {
+        await runManagedPm2Command({
+            manifestPath: options.manifestPath,
+            runtimeRoot: options.runtimeRoot,
+            service,
+            action: "start",
+            nameIdentifierValue: options.instanceName?.trim()
+        });
+    }
+}
+export async function resolveManagedServerEnvironment(options) {
+    const serverConfig = await getManagedServerConfig({
+        manifestPath: options.manifestPath,
+        runtimeRoot: options.runtimeRoot
     });
+    const sharedDataRoot = dirname(dirname(serverConfig.configPath));
+    const systemDataRoot = join(sharedDataRoot, "data");
+    const integrationEnvironment = await resolveManagedServerIntegrationEnvironment(options);
+    return {
+        host: serverConfig.host,
+        port: serverConfig.port,
+        aspNetCoreUrls: serverConfig.aspNetCoreUrls,
+        configPath: serverConfig.configPath,
+        sharedDataRoot,
+        environment: {
+            ASPNETCORE_URLS: serverConfig.aspNetCoreUrls,
+            Urls: serverConfig.aspNetCoreUrls,
+            DATADIR: systemDataRoot,
+            ...integrationEnvironment
+        }
+    };
+}
+async function resolveManagedServerIntegrationEnvironment(options) {
+    const manifest = await loadRuntimeManifest({ manifestPath: options.manifestPath });
+    const paths = resolveRuntimePaths(manifest, { runtimeRoot: options.runtimeRoot });
+    return {
+        ...(await resolveManagedVsCodeServerEnvironment(manifest.componentMap.get("code-server"), paths)),
+        ...(await resolveManagedOmniRouteEnvironment(manifest.componentMap.get("omniroute"), paths))
+    };
+}
+async function resolveManagedVsCodeServerEnvironment(component, paths) {
+    if (!component) {
+        return {};
+    }
+    const config = await readYamlObject(join(getComponentConfigDirectory(paths, component.name, component.runtimeDataDir), "config.yaml"));
+    const address = parseConfiguredAddress(readConfigString(config, "bind-addr"), DEFAULT_CODE_SERVER_HOST, DEFAULT_CODE_SERVER_PORT);
+    const authMode = readConfigString(config, "auth") ?? DEFAULT_CODE_SERVER_AUTH_MODE;
+    const secret = readConfigString(config, "password");
+    return {
+        VsCodeServer__Host: address.host,
+        VsCodeServer__Port: String(address.port),
+        VsCodeServer__AuthMode: authMode,
+        VsCodeServer__Source: VSCODE_SERVER_SOURCE_EXTERNAL,
+        VsCodeServer__SourceLocked: "true",
+        ...(secret
+            ? {
+                VsCodeServer__Secret: secret,
+                VsCodeServer__SecretSource: VSCODE_SERVER_SECRET_SOURCE_BOOTSTRAP
+            }
+            : {})
+    };
+}
+async function resolveManagedOmniRouteEnvironment(component, paths) {
+    if (!component) {
+        return {};
+    }
+    const config = await readYamlObject(join(getComponentConfigDirectory(paths, component.name, component.runtimeDataDir), "config.yaml"));
+    const address = parseConfiguredAddress(readConfigString(config, "listen"), DEFAULT_OMNIROUTE_HOST, DEFAULT_OMNIROUTE_PORT);
+    const baseUrl = buildHttpBaseUrl(address.host, address.port);
+    return {
+        OmniRoute__Enabled: "true",
+        OmniRoute__ApiEndpoint: baseUrl,
+        OmniRoute__DefaultBaseUrl: baseUrl,
+        OmniRoute__DefaultBaseUrlSource: OMNIROUTE_SOURCE_EXTERNAL,
+        OmniRoute__DefaultBaseUrlLocked: "true"
+    };
+}
+async function readYamlObject(filePath) {
+    try {
+        const content = await readFile(filePath, "utf8");
+        const parsed = parseYaml(content);
+        return isRecord(parsed) ? parsed : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function parseConfiguredAddress(value, defaultHost, defaultPort) {
+    if (!value) {
+        return { host: defaultHost, port: defaultPort };
+    }
+    try {
+        const parsed = new URL(value.includes("://") ? value : `http://${value}`);
+        const host = parsed.hostname || defaultHost;
+        const port = Number(parsed.port || String(defaultPort));
+        if (!Number.isInteger(port) || port < 1 || port > 65535) {
+            return { host: defaultHost, port: defaultPort };
+        }
+        return { host, port };
+    }
+    catch {
+        return { host: defaultHost, port: defaultPort };
+    }
+}
+function buildHttpBaseUrl(host, port) {
+    return new URL(`http://${host}:${port}`).toString();
+}
+function readConfigString(config, key) {
+    const value = config?.[key];
+    if (typeof value !== "string") {
+        return undefined;
+    }
+    const normalized = value.trim();
+    return normalized ? normalized : undefined;
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 async function resolveServerArchive(options, logger) {
+    const useHttpIndex = options.indexUrl !== undefined ||
+        options.indexChannel !== undefined ||
+        options.indexVersion !== undefined;
     const selectedModes = [
         options.archivePath ? "archive" : null,
         options.packageDirectory ? "package-directory" : null,
-        options.url ? "url" : null
+        options.url ? "url" : null,
+        useHttpIndex ? "index-url" : null
     ].filter(Boolean);
     if (selectedModes.length > 1) {
         throw new ManagedServerError("Choose only one server package source: --archive, --package-dir, or --url.");
@@ -157,8 +390,56 @@ async function resolveServerArchive(options, logger) {
             url: options.url
         }, options);
     }
+    if (useHttpIndex) {
+        return resolveHttpIndexArchive(options);
+    }
+    try {
+        return await resolveHttpIndexArchive(options);
+    }
+    catch (error) {
+        logger(`Default HTTP index ${DEFAULT_SERVER_HTTP_INDEX_URL} unavailable. Falling back to GitHub release source.`);
+        if (error instanceof ManagedServerError) {
+            logger(`HTTP index resolution detail: ${error.message}`);
+        }
+    }
     return resolveGitHubReleaseArchive(options);
 }
+async function resolveHttpIndexArchive(options) {
+    const fetchImpl = options.fetchImpl ?? globalThis.fetch;
+    if (typeof fetchImpl !== "function") {
+        throw new ManagedServerError("Global fetch is unavailable for HTTP index download.");
+    }
+    const indexUrl = normalizeOfficialServerHttpIndexUrl(options.indexUrl);
+    const response = await fetchImpl(indexUrl, {
+        headers: {
+            Accept: "application/json",
+            "User-Agent": "@hagicode/hagiscript"
+        }
+    });
+    if (!response.ok) {
+        throw new ManagedServerError(`Failed to read HTTP index from ${indexUrl}: HTTP ${response.status}`);
+    }
+    const indexPayload = (await response.json());
+    const selection = selectArchiveFromHttpIndex(indexPayload, {
+        indexUrl,
+        channel: options.indexChannel,
+        version: options.indexVersion,
+        assetName: options.assetName
+    });
+    return downloadRemoteArchive({
+        kind: "http-index",
+        locator: selection.locator,
+        assetName: selection.assetName,
+        version: selection.version,
+        url: selection.downloadUrl
+    }, options);
+}
+function normalizeOfficialServerHttpIndexUrl(indexUrl) {
+    const normalized = indexUrl?.trim() || DEFAULT_SERVER_HTTP_INDEX_URL;
+    return LEGACY_SERVER_HTTP_INDEX_URLS.has(normalized)
+        ? DEFAULT_SERVER_HTTP_INDEX_URL
+        : normalized;
+}
 async function resolveGitHubReleaseArchive(options) {
     const fetchImpl = options.fetchImpl ?? globalThis.fetch;
     if (typeof fetchImpl !== "function") {
@@ -237,23 +518,200 @@ async function downloadRemoteArchive(source, options) {
         throw error;
     }
 }
+function selectArchiveFromHttpIndex(payload, options) {
+    const desiredVersion = options.version?.trim() || null;
+    const desiredChannel = options.channel?.trim() || null;
+    const desiredAssetName = options.assetName?.trim() || null;
+    const defaultSuffix = getDefaultManagedServerAssetSuffix();
+    const versionEntries = asArray(payload.versions)
+        .map((entry) => normalizeHttpIndexVersionEntry(entry))
+        .filter((entry) => entry !== null);
+    const indexLevelAssets = asArray(payload.assets)
+        .map((entry) => normalizeHttpIndexAssetEntry(entry))
+        .filter((entry) => entry !== null);
+    const candidateVersions = versionEntries.filter((entry) => {
+        if (desiredVersion && entry.version !== desiredVersion) {
+            return false;
+        }
+        if (desiredChannel && !entry.channels.has(desiredChannel)) {
+            return false;
+        }
+        return true;
+    });
+    const orderedVersions = candidateVersions
+        .slice()
+        .sort((left, right) => compareVersionValues(left.version, right.version));
+    for (const versionEntry of orderedVersions) {
+        const match = selectHttpIndexAsset(versionEntry.assets, {
+            desiredAssetName,
+            defaultSuffix
+        });
+        if (match) {
+            return {
+                locator: `${options.indexUrl}@${versionEntry.version ?? "unknown"}`,
+                version: versionEntry.version,
+                assetName: match.assetName,
+                downloadUrl: match.downloadUrl
+            };
+        }
+    }
+    if (!desiredVersion && !desiredChannel && indexLevelAssets.length > 0) {
+        const match = selectHttpIndexAsset(indexLevelAssets, {
+            desiredAssetName,
+            defaultSuffix
+        });
+        if (match) {
+            return {
+                locator: `${options.indexUrl}@index`,
+                version: null,
+                assetName: match.assetName,
+                downloadUrl: match.downloadUrl
+            };
+        }
+    }
+    const scope = [
+        desiredVersion ? `version=${desiredVersion}` : null,
+        desiredChannel ? `channel=${desiredChannel}` : null,
+        desiredAssetName ? `asset=${desiredAssetName}` : null
+    ]
+        .filter(Boolean)
+        .join(", ");
+    throw new ManagedServerError(`HTTP index ${options.indexUrl} does not expose a matching server archive${scope ? ` (${scope})` : ""}.`);
+}
+function normalizeHttpIndexVersionEntry(value) {
+    if (!value || typeof value !== "object") {
+        return null;
+    }
+    const entry = value;
+    const version = normalizeString(entry.version) ?? normalizeString(entry.tag) ?? null;
+    const channels = new Set();
+    const singleChannel = normalizeString(entry.channel);
+    if (singleChannel) {
+        channels.add(singleChannel);
+    }
+    for (const item of asArray(entry.channels)) {
+        const normalized = normalizeString(item);
+        if (normalized) {
+            channels.add(normalized);
+        }
+    }
+    const assets = [...asArray(entry.assets), ...asArray(entry.files)]
+        .map((item) => normalizeHttpIndexAssetEntry(item))
+        .filter((item) => item !== null);
+    return {
+        version,
+        channels,
+        assets
+    };
+}
+function normalizeHttpIndexAssetEntry(value) {
+    if (!value || typeof value !== "object") {
+        return null;
+    }
+    const entry = value;
+    const assetName = normalizeString(entry.name);
+    const directUrl = normalizeString(entry.url) ??
+        normalizeString(entry.directUrl) ??
+        normalizeString(entry.downloadUrl) ??
+        normalizeString(entry.browser_download_url) ??
+        normalizeString(entry.browserDownloadUrl);
+    if (assetName && directUrl) {
+        return {
+            assetName,
+            downloadUrl: directUrl
+        };
+    }
+    const sourceUrl = resolveHttpIndexDownloadSourceUrl(entry.downloadSources ?? entry.sources);
+    if (!assetName || !sourceUrl) {
+        return null;
+    }
+    return {
+        assetName,
+        downloadUrl: sourceUrl
+    };
+}
+function resolveHttpIndexDownloadSourceUrl(value) {
+    const sources = asArray(value)
+        .map((entry) => {
+        if (!entry || typeof entry !== "object") {
+            return null;
+        }
+        const source = entry;
+        const url = normalizeString(source.url);
+        if (!url) {
+            return null;
+        }
+        return {
+            url,
+            primary: source.primary === true
+        };
+    })
+        .filter((entry) => !!entry);
+    if (sources.length === 0) {
+        return null;
+    }
+    return sources.find((entry) => entry.primary)?.url ?? sources[0].url;
+}
+function selectHttpIndexAsset(assets, options) {
+    if (options.desiredAssetName) {
+        return assets.find((entry) => entry.assetName === options.desiredAssetName) ?? null;
+    }
+    return (assets.find((entry) => entry.assetName.endsWith(options.defaultSuffix)) ??
+        assets[0] ??
+        null);
+}
+function asArray(value) {
+    return Array.isArray(value) ? value : [];
+}
+function normalizeString(value) {
+    if (typeof value !== "string") {
+        return undefined;
+    }
+    const normalized = value.trim();
+    return normalized ? normalized : undefined;
+}
+function compareVersionValues(left, right) {
+    if (left && right) {
+        const normalizedLeft = normalizeSemverLike(left);
+        const normalizedRight = normalizeSemverLike(right);
+        if (normalizedLeft && normalizedRight) {
+            return semver.rcompare(normalizedLeft, normalizedRight);
+        }
+    }
+    if (left === right) {
+        return 0;
+    }
+    if (left === null) {
+        return 1;
+    }
+    if (right === null) {
+        return -1;
+    }
+    return right.localeCompare(left);
+}
+function normalizeSemverLike(value) {
+    const normalized = value.startsWith("v") ? value.slice(1) : value;
+    return semver.valid(normalized);
+}
 async function stageServerArchive(options) {
     const extractRoot = await mkdtemp(join(tmpdir(), "hagiscript-server-extract-"));
-    const componentRoot = getComponentManagedRoot(options.paths, options.serverComponent.name);
-    const targetCurrentRoot = join(componentRoot, "current");
+    const targetVersionRoot = getServerVersionRoot(options.paths, options.version);
     try {
         await (options.extractArchive ?? extractManagedServerArchive)(options.archivePath, extractRoot, options.runner);
         const payloadRoot = await locateManagedServerPayloadRoot(extractRoot);
-        const stagedDllPath = join(targetCurrentRoot, "lib", "PCode.Web.dll");
-        await mkdir(componentRoot, { recursive: true });
-        await rm(targetCurrentRoot, { recursive: true, force: true });
-        await cp(payloadRoot, targetCurrentRoot, {
+        const stagedDllPath = join(targetVersionRoot, "lib", "PCode.Web.dll");
+        if ((await pathExists(targetVersionRoot)) && !options.force) {
+            throw new ManagedServerError(`Managed server version ${options.version} is already installed at ${targetVersionRoot}. Use --force to replace it.`);
+        }
+        await mkdir(targetVersionRoot, { recursive: true });
+        await rm(targetVersionRoot, { recursive: true, force: true });
+        await cp(payloadRoot, targetVersionRoot, {
             recursive: true,
             force: true
         });
-        await assertValidManagedServerPayload(targetCurrentRoot);
+        await assertValidManagedServerPayload(targetVersionRoot);
         return {
-            stagedPath: targetCurrentRoot,
+            stagedPath: targetVersionRoot,
             stagedDllPath
         };
     }
@@ -261,40 +719,6 @@ async function stageServerArchive(options) {
         await rm(extractRoot, { recursive: true, force: true }).catch(() => undefined);
     }
 }
-async function ensureManagedPm2(options) {
-    const syncNpmGlobalsFn = options.syncNpmGlobalsFn ?? syncNpmGlobals;
-    const tempDirectory = await mkdtemp(join(tmpdir(), "hagiscript-pm2-manifest-"));
-    const manifestPath = join(tempDirectory, "manifest.json");
-    const versionRange = normalizePm2Version(options.pm2Version);
-    try {
-        await writeFile(manifestPath, `${JSON.stringify({
-            packages: {
-                pm2: {
-                    version: versionRange,
-                    ...(semver.valid(versionRange) ? { target: versionRange } : {})
-                }
-            }
-        }, null, 2)}\n`);
-        const summary = await syncNpmGlobalsFn({
-            runtimePath: options.paths.nodeRuntime,
-            manifestPath,
-            registryMirror: options.registryMirror,
-            force: options.force,
-            npmOptions: {
-                prefix: options.paths.npmPrefix
-            },
-            onLog: (event) => {
-                if (event.type === "summary") {
-                    options.logger(`Managed pm2 ready in ${options.paths.npmPrefix} (${event.summary.changedCount} change(s))`);
-                }
-            }
-        });
-        return summary;
-    }
-    finally {
-        await rm(tempDirectory, { recursive: true, force: true }).catch(() => undefined);
-    }
-}
 async function selectServerArchiveFromDirectory(directory, assetName) {
     const entries = await readdir(directory, { withFileTypes: true });
     const zipFiles = entries
@@ -343,7 +767,7 @@ async function extractManagedServerArchive(archivePath, extractRoot, runner) {
     try {
         await runner("unzip", ["-q", archivePath, "-d", extractRoot]);
     }
-    catch (error) {
+    catch {
         await runner("bsdtar", ["-xf", archivePath, "-C", extractRoot], {
             maxBuffer: 10 * 1024 * 1024
         });
@@ -416,6 +840,15 @@ function extractVersionFromServerAssetName(assetName) {
     const match = new RegExp(`^hagicode-(.+)-${suffix}$`, "u").exec(assetName);
     return match?.[1] ?? null;
 }
+function resolveManagedServerVersion(archive) {
+    const detectedVersion = archive.version ?? extractVersionFromServerAssetName(archive.assetName);
+    const normalizedSemver = detectedVersion ? normalizeSemverLike(detectedVersion) : null;
+    const normalizedVersion = normalizedSemver ?? detectedVersion?.trim() ?? "";
+    if (!normalizedVersion) {
+        throw new ManagedServerError(`Unable to determine a concrete server version from ${archive.assetName}. Use a versioned archive name such as hagicode-1.2.3-${getDefaultManagedServerAssetSuffix()}.`);
+    }
+    return normalizedVersion;
+}
 function inferArchiveNameFromUrl(urlValue) {
     try {
         const parsed = new URL(urlValue);