hagiscript-sdk 0.2.9-dev.1780142424.1.dedbfb7

package/dist/src/runtime/server-manager.js

@@ -0,0 +1,946 @@
+import { cp, mkdtemp, mkdir, readFile, readdir, rm, stat, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+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 { resolveManagedPm2Environment, runManagedPm2Command, supportedPm2Services } from "./pm2-manager.js";
+import { loadRuntimeManifest } from "./runtime-manifest.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";
+import { extractZipArchive } from "./zip-extract.js";
+export class ManagedServerError extends Error {
+    constructor(message, options) {
+        super(message, options);
+        this.name = "ManagedServerError";
+    }
+}
+const MANAGED_SERVER_REMOVE_RETRY_COUNT = 30;
+const MANAGED_SERVER_REMOVE_RETRY_DELAY_MS = 1_000;
+const DEFAULT_GITHUB_REPOSITORY = "HagiCode-org/releases";
+const DEFAULT_GITHUB_TAG = "latest";
+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 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: runtimeDependencyComponents,
+            force: options.force ?? false,
+            downloadCache: options.downloadCache,
+            downloadCacheDir: options.downloadCacheDir,
+            npmRegistryMirror: options.registryMirror,
+            pm2VersionOverride: options.pm2Version,
+            logger
+        });
+        if (options.ensurePm2 ?? true) {
+            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,
+            runtimeRoot: options.runtimeRoot
+        });
+        return {
+            source: {
+                kind: archive.kind,
+                locator: archive.locator,
+                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)
+            }
+        };
+    }
+    finally {
+        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.`);
+    }
+    if (state.activeVersion === version) {
+        throw new ManagedServerError(`Managed server version ${version} is currently active and cannot be removed.`);
+    }
+    await removeManagedServerInstallPath(installedVersion.installPath, options);
+    const nextState = await removeInstalledManagedServerVersion(context.statePath, version);
+    return {
+        activeVersion: nextState.activeVersion,
+        removedVersion: version,
+        removedPath: installedVersion.installPath,
+        statePath: context.statePath
+    };
+}
+async function removeManagedServerInstallPath(installPath, options) {
+    const removeDirectoryFn = options.removeDirectoryFn ?? rm;
+    const retryDelayMs = options.retryDelayMs ?? MANAGED_SERVER_REMOVE_RETRY_DELAY_MS;
+    for (let attempt = 0;; attempt += 1) {
+        try {
+            await removeDirectoryFn(installPath, { recursive: true, force: true });
+            return;
+        }
+        catch (error) {
+            if (!isRetryableManagedServerRemoveError(error) ||
+                attempt >= MANAGED_SERVER_REMOVE_RETRY_COUNT - 1) {
+                throw error;
+            }
+            await delay(retryDelayMs);
+        }
+    }
+}
+function isRetryableManagedServerRemoveError(error) {
+    const code = error?.code;
+    return code === "EBUSY" || code === "EPERM" || code === "ENOTEMPTY";
+}
+function delay(ms) {
+    return new Promise((resolve) => globalThis.setTimeout(resolve, ms));
+}
+export async function restartManagedServer(options = {}) {
+    return runManagedServerAction("restart", options);
+}
+export async function stopManagedServer(options = {}) {
+    return runManagedServerAction("stop", options);
+}
+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(),
+        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(),
+        environmentOverrides
+    });
+}
+async function ensureManagedServerDependenciesStarted(options) {
+    const manifest = await loadRuntimeManifest({ manifestPath: options.manifestPath });
+    const runtimeState = await queryRuntimeState({
+        manifestPath: options.manifestPath,
+        runtimeRoot: options.runtimeRoot
+    });
+    const managedPm2ServiceNames = new Set(supportedPm2Services);
+    const dependencyServices = MANAGED_SERVER_INTEGRATION_DEPENDENCIES.filter((service) => service !== "server" &&
+        managedPm2ServiceNames.has(service) &&
+        isManagedDependencyInstalled(runtimeState, 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 });
+    const runtimeState = await queryRuntimeState({
+        manifestPath: options.manifestPath,
+        runtimeRoot: options.runtimeRoot
+    });
+    return {
+        ...(await resolveManagedVsCodeServerEnvironment(isManagedDependencyInstalled(runtimeState, "code-server")
+            ? manifest.componentMap.get("code-server")
+            : undefined, paths, manifest)),
+        ...(await resolveManagedOmniRouteEnvironment(isManagedDependencyInstalled(runtimeState, "omniroute")
+            ? manifest.componentMap.get("omniroute")
+            : undefined, paths, manifest))
+    };
+}
+async function resolveManagedVsCodeServerEnvironment(component, paths, manifest) {
+    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 exposedPort = resolveManagedDependencyPublicPort(manifest, "code-server") ?? address.port;
+    const authMode = readConfigString(config, "auth") ?? DEFAULT_CODE_SERVER_AUTH_MODE;
+    const secret = readConfigString(config, "password");
+    return {
+        VsCodeServer__Host: address.host,
+        VsCodeServer__Port: String(exposedPort),
+        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, manifest) {
+    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 exposedPort = resolveManagedDependencyPublicPort(manifest, "omniroute") ?? address.port;
+    const baseUrl = buildHttpBaseUrl(address.host, exposedPort);
+    return {
+        OmniRoute__Enabled: "true",
+        OmniRoute__ApiEndpoint: baseUrl,
+        OmniRoute__DefaultBaseUrl: baseUrl,
+        OmniRoute__DefaultBaseUrlSource: OMNIROUTE_SOURCE_EXTERNAL,
+        OmniRoute__DefaultBaseUrlLocked: "true"
+    };
+}
+function isManagedDependencyInstalled(runtimeState, componentName) {
+    return runtimeState.components.some((component) => component.name === componentName && component.status === "installed");
+}
+function resolveManagedDependencyPublicPort(manifest, service) {
+    const publicConfig = manifest.proxy?.caddy?.public;
+    if (!publicConfig) {
+        return undefined;
+    }
+    return service === "code-server" ? publicConfig.codeServerPort : publicConfig.omniroutePort;
+}
+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,
+        useHttpIndex ? "index-url" : null
+    ].filter(Boolean);
+    if (selectedModes.length > 1) {
+        throw new ManagedServerError("Choose only one server package source: --archive, --package-dir, or --url.");
+    }
+    if (options.archivePath) {
+        const archivePath = resolve(options.archivePath);
+        await assertFileExists(archivePath, `Server archive not found: ${archivePath}`);
+        logger(`Using local server archive ${archivePath}`);
+        return {
+            kind: "local-archive",
+            locator: archivePath,
+            version: null,
+            assetName: basename(archivePath),
+            archivePath,
+            cleanup: async () => undefined
+        };
+    }
+    if (options.packageDirectory) {
+        const directory = resolve(options.packageDirectory);
+        const selection = await selectServerArchiveFromDirectory(directory, options.assetName);
+        logger(`Selected ${selection.assetName} from ${directory}`);
+        return {
+            kind: "local-folder",
+            locator: directory,
+            version: selection.version,
+            assetName: selection.assetName,
+            archivePath: selection.archivePath,
+            cleanup: async () => undefined
+        };
+    }
+    if (options.url) {
+        return downloadRemoteArchive({
+            kind: "direct-url",
+            locator: options.url,
+            assetName: inferArchiveNameFromUrl(options.url),
+            version: null,
+            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") {
+        throw new ManagedServerError("Global fetch is unavailable for GitHub release download.");
+    }
+    const repository = options.githubRepository?.trim() || DEFAULT_GITHUB_REPOSITORY;
+    const tag = options.githubTag?.trim() || DEFAULT_GITHUB_TAG;
+    const releaseEndpoint = tag === "latest"
+        ? `https://api.github.com/repos/${repository}/releases/latest`
+        : `https://api.github.com/repos/${repository}/releases/tags/${encodeURIComponent(tag)}`;
+    const response = await fetchImpl(releaseEndpoint, {
+        headers: buildGitHubRequestHeaders(options.githubToken, "application/vnd.github+json")
+    });
+    if (!response.ok) {
+        throw new ManagedServerError(`Failed to read GitHub release metadata from ${repository}: HTTP ${response.status}`);
+    }
+    const release = (await response.json());
+    const desiredAssetName = options.assetName?.trim() || null;
+    const defaultSuffix = getDefaultManagedServerAssetSuffix();
+    const asset = Array.isArray(release.assets)
+        ? release.assets.find((entry) => desiredAssetName
+            ? entry?.name === desiredAssetName
+            : typeof entry?.name === "string" && entry.name.endsWith(defaultSuffix))
+        : undefined;
+    if (!asset?.name || !asset.browser_download_url) {
+        throw new ManagedServerError(desiredAssetName
+            ? `GitHub release ${tag} in ${repository} does not expose asset ${desiredAssetName}.`
+            : `GitHub release ${tag} in ${repository} does not expose an asset ending with ${defaultSuffix}.`);
+    }
+    return downloadRemoteArchive({
+        kind: "github-release",
+        locator: `${repository}@${release.tag_name ?? tag}`,
+        assetName: asset.name,
+        version: release.tag_name ?? null,
+        url: asset.browser_download_url
+    }, options);
+}
+async function downloadRemoteArchive(source, options) {
+    const fetchImpl = options.fetchImpl ?? globalThis.fetch;
+    if (typeof fetchImpl !== "function") {
+        throw new ManagedServerError("Global fetch is unavailable for server download.");
+    }
+    const tempDirectory = await mkdtemp(join(tmpdir(), "hagiscript-server-download-"));
+    const archivePath = join(tempDirectory, source.assetName);
+    const cachePath = isDownloadCacheEnabled(options.downloadCache)
+        ? join(resolveDownloadCacheDirectory(options.downloadCacheDir), "server", createHash("sha256").update(source.url).digest("hex"), source.assetName)
+        : undefined;
+    try {
+        const restoredSize = cachePath ? await copyFileFromCache(cachePath, archivePath) : undefined;
+        if (restoredSize === undefined) {
+            const response = await fetchImpl(source.url, {
+                headers: buildGitHubRequestHeaders(options.githubToken, "application/octet-stream")
+            });
+            if (!response.ok) {
+                throw new ManagedServerError(`Failed to download ${source.url}: HTTP ${response.status}`);
+            }
+            const buffer = Buffer.from(await response.arrayBuffer());
+            await writeFile(archivePath, buffer);
+            if (cachePath) {
+                await storeFileInCache(archivePath, cachePath);
+            }
+        }
+        return {
+            kind: source.kind,
+            locator: source.locator,
+            version: source.version,
+            assetName: source.assetName,
+            archivePath,
+            cleanup: async () => {
+                await rm(tempDirectory, { recursive: true, force: true });
+            }
+        };
+    }
+    catch (error) {
+        await rm(tempDirectory, { recursive: true, force: true }).catch(() => undefined);
+        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 targetVersionRoot = getServerVersionRoot(options.paths, options.version);
+    try {
+        await (options.extractArchive ?? extractManagedServerArchive)(options.archivePath, extractRoot, options.runner);
+        const payloadRoot = await locateManagedServerPayloadRoot(extractRoot);
+        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(targetVersionRoot);
+        return {
+            stagedPath: targetVersionRoot,
+            stagedDllPath
+        };
+    }
+    finally {
+        await rm(extractRoot, { recursive: true, force: true }).catch(() => undefined);
+    }
+}
+async function selectServerArchiveFromDirectory(directory, assetName) {
+    const entries = await readdir(directory, { withFileTypes: true });
+    const zipFiles = entries
+        .filter((entry) => entry.isFile() && entry.name.endsWith(".zip"))
+        .map((entry) => entry.name);
+    if (zipFiles.length === 0) {
+        throw new ManagedServerError(`No .zip archives found in ${directory}.`);
+    }
+    const desiredAssetName = assetName?.trim() || null;
+    if (desiredAssetName) {
+        const matched = zipFiles.find((entry) => entry === desiredAssetName);
+        if (!matched) {
+            throw new ManagedServerError(`Archive ${desiredAssetName} was not found in ${directory}.`);
+        }
+        return {
+            archivePath: join(directory, matched),
+            assetName: matched,
+            version: extractVersionFromServerAssetName(matched)
+        };
+    }
+    const suffix = getDefaultManagedServerAssetSuffix();
+    const candidates = zipFiles
+        .filter((entry) => entry.endsWith(suffix))
+        .map((entry) => ({
+        assetName: entry,
+        archivePath: join(directory, entry),
+        version: extractVersionFromServerAssetName(entry)
+    }))
+        .filter((entry) => entry.version && semver.valid(entry.version))
+        .sort((left, right) => semver.rcompare(String(left.version), String(right.version)));
+    if (candidates.length === 0) {
+        throw new ManagedServerError(`No server archive ending with ${suffix} was found in ${directory}.`);
+    }
+    return candidates[0];
+}
+async function extractManagedServerArchive(archivePath, extractRoot, _runner) {
+    try {
+        await extractZipArchive(archivePath, extractRoot);
+    }
+    catch (error) {
+        const archiveError = error instanceof Error ? error : new Error(String(error));
+        throw new ManagedServerError(`Failed to extract managed server archive ${archivePath}: ${archiveError.message}`, { cause: archiveError });
+    }
+}
+async function locateManagedServerPayloadRoot(extractRoot) {
+    const searchQueue = [extractRoot];
+    while (searchQueue.length > 0) {
+        const current = searchQueue.shift();
+        if (!current) {
+            continue;
+        }
+        const dllPath = join(current, "lib", "PCode.Web.dll");
+        if (await pathExists(dllPath)) {
+            return current;
+        }
+        const entries = await readdir(current, { withFileTypes: true });
+        for (const entry of entries) {
+            if (entry.isDirectory()) {
+                searchQueue.push(join(current, entry.name));
+            }
+        }
+    }
+    throw new ManagedServerError(`Extracted server archive does not contain lib/PCode.Web.dll under ${extractRoot}.`);
+}
+async function assertValidManagedServerPayload(payloadRoot) {
+    for (const relativePath of [
+        "lib/PCode.Web.dll",
+        "lib/PCode.Web.deps.json",
+        "lib/PCode.Web.runtimeconfig.json"
+    ]) {
+        await assertFileExists(join(payloadRoot, relativePath), `Managed server payload is missing required file ${relativePath}.`);
+    }
+}
+function assertServerComponent(component) {
+    if (!component) {
+        throw new ManagedServerError("Runtime manifest does not define a server component.");
+    }
+    if (component.type !== "released-service") {
+        throw new ManagedServerError("Runtime manifest server component must be a released-service.");
+    }
+    return component;
+}
+async function assertFileExists(pathValue, message) {
+    const target = resolve(pathValue);
+    try {
+        const result = await stat(target);
+        if (!result.isFile()) {
+            throw new ManagedServerError(message);
+        }
+    }
+    catch (error) {
+        if (error instanceof ManagedServerError) {
+            throw error;
+        }
+        throw new ManagedServerError(message, error instanceof Error ? { cause: error } : undefined);
+    }
+}
+async function pathExists(pathValue) {
+    try {
+        await stat(pathValue);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function extractVersionFromServerAssetName(assetName) {
+    const suffix = getDefaultManagedServerAssetSuffix().replace(/[.*+?^${}()|[\]\\]/gu, "\\$&");
+    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);
+        const candidate = basename(parsed.pathname);
+        return candidate || "hagicode-server.zip";
+    }
+    catch {
+        return "hagicode-server.zip";
+    }
+}
+function normalizePm2Version(pm2Version) {
+    const normalized = pm2Version?.trim();
+    return normalized && normalized.length > 0 ? normalized : "*";
+}
+function getDefaultManagedServerAssetSuffix() {
+    return `${getManagedServerPlatform()}-${getManagedServerArchitecture()}-nort.zip`;
+}
+function getManagedServerPlatform(platform = process.platform) {
+    switch (platform) {
+        case "linux":
+            return "linux";
+        case "win32":
+            return "win";
+        case "darwin":
+            return "osx";
+        default:
+            throw new ManagedServerError(`Unsupported server package platform: ${platform}`);
+    }
+}
+function getManagedServerArchitecture(arch = process.arch) {
+    switch (arch) {
+        case "x64":
+            return "x64";
+        case "arm64":
+            return "arm64";
+        default:
+            throw new ManagedServerError(`Unsupported server package architecture: ${arch}`);
+    }
+}
+function buildGitHubRequestHeaders(githubToken, accept = "application/json") {
+    const token = githubToken?.trim() || process.env.GITHUB_TOKEN?.trim() || process.env.GH_TOKEN?.trim();
+    return {
+        Accept: accept,
+        "User-Agent": "@hagicode/hagiscript",
+        ...(token ? { Authorization: `Bearer ${token}` } : {})
+    };
+}
+//# sourceMappingURL=server-manager.js.map