openxiangda-devkit-core 2.0.0-alpha.16 → 2.0.0-alpha.19

package/dist/local-development.js

@@ -0,0 +1,802 @@
+import { spawn, spawnSync } from "node:child_process";
+import { createHash, randomBytes, scryptSync } from "node:crypto";
+import { createWriteStream, existsSync, mkdirSync, readFileSync, realpathSync, renameSync, rmSync, statSync, writeFileSync, } from "node:fs";
+import { createServer } from "node:net";
+import { join } from "node:path";
+import { resetLocalPostgres, startLocalPostgres, stopOwnedLocalPostgres, stopLocalPostgres, } from "./local-postgres.js";
+const LOOPBACK_HOST = "127.0.0.1";
+const DEFAULT_WEB_PORT = 5173;
+const DEFAULT_APP_PORT = 3000;
+const DEFAULT_PLATFORM_PORT = 7001;
+const DEFAULT_DATABASE_PORT = 54329;
+export async function runLocalDevelopment(input) {
+    const databaseRuntime = input.databaseRuntime || {
+        start: startLocalPostgres,
+        stop: stopLocalPostgres,
+        reset: resetLocalPostgres,
+    };
+    const root = realpathSync(input.root);
+    const paths = localPaths(root);
+    mkdirSync(paths.root, { recursive: true, mode: 0o700 });
+    mkdirSync(paths.logs, { recursive: true, mode: 0o700 });
+    const existing = await acquireSessionLock(paths, root);
+    if (existing) {
+        input.onStatus?.(`本地开发会话已运行：${existing.urls.web}`);
+        if (!input.noOpen)
+            openBrowser(existing.urls.web);
+        return {
+            exitCode: 0,
+            reused: true,
+            session: existing,
+            diagnosticsPath: paths.diagnostics,
+            logPath: paths.log,
+        };
+    }
+    const { databaseResetPrepared, webPort, appPort, platformPort, databasePort, startedAt, session, runtimeOAuthCredential, eventCredential, localManifest, } = await prepareLocalDevelopmentSession(input, databaseRuntime, root, paths);
+    const children = [];
+    const exitPromises = [];
+    let log;
+    let postgres;
+    let stopping = false;
+    let stopTimer;
+    const signalHandlers = new Map();
+    const cleanup = () => {
+        for (const [signal, handler] of signalHandlers) {
+            process.off(signal, handler);
+        }
+        if (stopTimer)
+            clearTimeout(stopTimer);
+        log?.end();
+        rmSync(paths.lockDirectory, { recursive: true, force: true });
+    };
+    const stop = (signal) => {
+        if (stopping)
+            return;
+        stopping = true;
+        session.status = "stopping";
+        writeJsonAtomic(paths.diagnostics, session);
+        terminateChildren(children, signal);
+        stopTimer = setTimeout(() => terminateChildren(children, "SIGKILL"), 5_000);
+        stopTimer.unref();
+    };
+    try {
+        log = createWriteStream(paths.log, { flags: "a", mode: 0o600 });
+        log.write(`\n[${startedAt}] openxiangda dev ${session.workspaceId}\n`);
+        if (databasePort !== null) {
+            postgres = await databaseRuntime.start({
+                workspaceId: session.workspaceId,
+                port: databasePort,
+                credentialPath: paths.databaseCredential,
+                ...(input.reset === undefined
+                    ? {}
+                    : { reset: input.reset && !databaseResetPrepared }),
+                ...(input.onStatus ? { onStatus: input.onStatus } : {}),
+            });
+            session.database = {
+                engine: "postgresql",
+                containerName: postgres.containerName,
+                volumeName: postgres.volumeName,
+                image: postgres.image,
+            };
+            writeJsonAtomic(paths.lockMetadata, session);
+            writeJsonAtomic(paths.diagnostics, session);
+        }
+        const environment = {
+            ...process.env,
+            PORT: appPort === null ? undefined : String(appPort),
+            OPENXIANGDA_APP_CODE: input.appCode,
+            OPENXIANGDA_APP_PORT: appPort === null ? "" : String(appPort),
+            OPENXIANGDA_WEB_PORT: String(webPort),
+            OPENXIANGDA_PLATFORM_PORT: platformPort === null ? "" : String(platformPort),
+            OPENXIANGDA_DEV_HOST: LOOPBACK_HOST,
+            OPENXIANGDA_ENVIRONMENT_KEY: "local",
+            OPENXIANGDA_ENVIRONMENT_ID: "local",
+            OPENXIANGDA_APP_VERSION_ID: "local-worktree",
+            OPENXIANGDA_DEPLOYMENT_RUN_ID: "local-development",
+            OPENXIANGDA_ENVIRONMENT_HEAD_REVISION: "1",
+            OPENXIANGDA_BACKEND_REVISION_ID: "local-worktree",
+            OPENXIANGDA_RUNTIME_MODE: "local",
+            OPENXIANGDA_PLATFORM_BASE_URL: session.urls.platform,
+            OPENXIANGDA_LOCAL_MOCK: input.uiOnly ? "true" : "false",
+            OPENXIANGDA_PLATFORM_PROXY: platformPort === null ? "" : `http://${LOOPBACK_HOST}:${platformPort}`,
+            OPENXIANGDA_UI_ONLY: input.uiOnly ? "true" : "false",
+            VITE_OPENXIANGDA_UI_ONLY: input.uiOnly ? "true" : "false",
+            OPENXIANGDA_LOCAL_MANIFEST_PATH: localManifest ? paths.manifest : "",
+        };
+        const eventEnvironment = Object.fromEntries(Object.entries(eventCredential?.secrets || {}).map(([code, secret]) => [
+            `OPENXIANGDA_EVENT_SECRET_${environmentCode(code)}`,
+            secret,
+        ]));
+        const spawnManaged = (command, extraEnvironment = {}) => {
+            const child = spawn("pnpm", ["run", command], {
+                cwd: root,
+                detached: process.platform !== "win32",
+                stdio: ["inherit", "pipe", "pipe"],
+                env: { ...environment, ...extraEnvironment },
+            });
+            children.push(child);
+            exitPromises.push(childExit(child));
+            pipeOutput(child.stdout, process.stdout, log);
+            pipeOutput(child.stderr, process.stderr, log);
+            return child;
+        };
+        const applicationChild = input.uiOnly
+            ? spawnManaged("dev:ui-only")
+            : spawnManaged("dev:web");
+        if (!input.uiOnly) {
+            spawnManaged("dev:server", {
+                ...eventEnvironment,
+                ...(runtimeOAuthCredential
+                    ? {
+                        OPENXIANGDA_OAUTH_CLIENT_ID: runtimeOAuthCredential.clientId,
+                        OPENXIANGDA_OAUTH_CLIENT_SECRET: runtimeOAuthCredential.clientSecret,
+                        OPENXIANGDA_OAUTH_SCOPES: runtimeOAuthCredential.scopes.join(" "),
+                    }
+                    : {}),
+            });
+            spawnManaged("dev:platform", {
+                ...eventEnvironment,
+                OPENXIANGDA_LOCAL_DATABASE_URL: postgres?.connectionString || "",
+                OPENXIANGDA_LOCAL_APP_BACKEND_URL: `http://${LOOPBACK_HOST}:${appPort}`,
+            });
+        }
+        if (applicationChild.pid !== undefined) {
+            session.childPid = applicationChild.pid;
+        }
+        session.childPids = children.flatMap(child => child.pid === undefined ? [] : [child.pid]);
+        writeJsonAtomic(paths.lockMetadata, session);
+        writeJsonAtomic(paths.diagnostics, session);
+        for (const signal of ["SIGINT", "SIGTERM"]) {
+            const handler = () => stop(signal);
+            signalHandlers.set(signal, handler);
+            process.once(signal, handler);
+        }
+        input.onStatus?.(`正在启动本地应用：${session.urls.web}`);
+        const startup = await Promise.race([
+            waitForLocalReadiness(session, children, input.readinessTimeoutMs).then(() => ({ kind: "ready" })),
+            Promise.race(exitPromises).then(exit => ({ kind: "exit", exit })),
+        ]);
+        if (startup.kind === "exit") {
+            throw new Error(startup.exit.error?.message ||
+                `OPENXIANGDA_LOCAL_PROCESS_EXITED: ${startup.exit.code}`);
+        }
+        session.status = "ready";
+        session.readyAt = new Date().toISOString();
+        writeJsonAtomic(paths.lockMetadata, session);
+        writeJsonAtomic(paths.diagnostics, session);
+        input.onStatus?.(input.uiOnly
+            ? `UI-only 预览已就绪（不能作为发布验证）：${session.urls.web}`
+            : `本地应用已就绪：${session.urls.web}`);
+        if (!input.noOpen)
+            openBrowser(session.urls.web);
+        const exit = await Promise.race(exitPromises);
+        terminateChildren(children, "SIGTERM");
+        const exits = await waitForChildrenExit(children, exitPromises);
+        const exitCode = stopping
+            ? 0
+            : exits.find(result => result.code !== 0)?.code ?? exit.code;
+        session.exitCode = exitCode;
+        session.stoppedAt = new Date().toISOString();
+        session.status = exitCode === 0 ? "stopped" : "failed";
+        const failure = exits.find(result => result.error)?.error;
+        if (failure)
+            session.failure = failure.message;
+        writeJsonAtomic(paths.diagnostics, session);
+        return {
+            exitCode,
+            reused: false,
+            session,
+            diagnosticsPath: paths.diagnostics,
+            logPath: paths.log,
+        };
+    }
+    catch (error) {
+        session.status = "failed";
+        session.exitCode = 1;
+        session.stoppedAt = new Date().toISOString();
+        session.failure = error instanceof Error ? error.message : String(error);
+        writeJsonAtomic(paths.diagnostics, session);
+        terminateChildren(children, "SIGTERM");
+        await waitForChildrenExit(children, exitPromises);
+        throw error;
+    }
+    finally {
+        try {
+            await databaseRuntime.stop(postgres);
+        }
+        finally {
+            cleanup();
+        }
+    }
+}
+export function localDevelopmentSession(root) {
+    const canonical = realpathSync(root);
+    return readActiveSession(localPaths(canonical).lockMetadata, canonical);
+}
+export function localDevelopmentStatus(root) {
+    const canonical = realpathSync(root);
+    const paths = localPaths(canonical);
+    const session = readActiveSession(paths.lockMetadata, canonical);
+    return {
+        active: Boolean(session),
+        session,
+        lastSession: readSession(paths.diagnostics, canonical),
+    };
+}
+export async function stopLocalDevelopment(root) {
+    const canonical = realpathSync(root);
+    const paths = localPaths(canonical);
+    assertSessionMetadataIsSafe(paths, canonical);
+    const session = readActiveSession(paths.lockMetadata, canonical);
+    if (!session) {
+        if (existsSync(paths.lockDirectory)) {
+            if (!existsSync(paths.lockMetadata) &&
+                Date.now() - statSync(paths.lockDirectory).mtimeMs < 10_000) {
+                throw new Error("OPENXIANGDA_LOCAL_SESSION_TRANSITION_IN_PROGRESS");
+            }
+            rmSync(paths.lockDirectory, { recursive: true, force: true });
+        }
+        const workspaceId = createHash("sha256")
+            .update(canonical)
+            .digest("hex")
+            .slice(0, 16);
+        const stoppedDatabase = await stopOwnedLocalPostgres(workspaceId).catch(error => {
+            if (/No such|not found/i.test(error.message))
+                return false;
+            throw error;
+        });
+        return {
+            stopped: stoppedDatabase,
+            stoppedDatabase,
+            session: readSession(paths.diagnostics, canonical),
+        };
+    }
+    if (process.platform !== "win32" && !session.ownerIdentity) {
+        throw new Error("OPENXIANGDA_LOCAL_SESSION_IDENTITY_REQUIRED");
+    }
+    if (session.ownerIdentity &&
+        processIdentity(session.ownerPid) !== session.ownerIdentity) {
+        throw new Error("OPENXIANGDA_LOCAL_SESSION_OWNER_CHANGED");
+    }
+    if (process.platform === "win32") {
+        const child = spawn("taskkill", ["/pid", String(session.ownerPid), "/t"], {
+            detached: true,
+            stdio: "ignore",
+        });
+        child.unref();
+    }
+    else {
+        process.kill(session.ownerPid, "SIGTERM");
+    }
+    const stopped = await waitForProcessStop(session.ownerPid, session.ownerIdentity, 15_000);
+    if (!stopped) {
+        throw new Error(`OPENXIANGDA_LOCAL_STOP_TIMEOUT:${session.ownerPid}`);
+    }
+    const completed = {
+        ...session,
+        status: "stopped",
+        exitCode: 0,
+        stoppedAt: new Date().toISOString(),
+    };
+    writeJsonAtomic(paths.diagnostics, completed);
+    rmSync(paths.lockDirectory, { recursive: true, force: true });
+    return {
+        stopped: true,
+        stoppedDatabase: Boolean(session.database),
+        session: completed,
+    };
+}
+export async function resetLocalDevelopmentData(root) {
+    const canonical = realpathSync(root);
+    const paths = localPaths(canonical);
+    assertSessionMetadataIsSafe(paths, canonical);
+    const existing = await acquireSessionLock(paths, canonical);
+    if (existing) {
+        throw new Error("OPENXIANGDA_LOCAL_RESET_SESSION_ACTIVE");
+    }
+    try {
+        const workspaceId = createHash("sha256")
+            .update(canonical)
+            .digest("hex")
+            .slice(0, 16);
+        const removedState = existsSync(paths.state);
+        const database = await resetLocalPostgres({
+            workspaceId,
+            credentialPath: paths.databaseCredential,
+        });
+        rmSync(paths.state, { recursive: true, force: true });
+        return { workspaceId, database, removedState };
+    }
+    finally {
+        rmSync(paths.lockDirectory, { recursive: true, force: true });
+    }
+}
+async function prepareLocalDevelopmentSession(input, databaseRuntime, root, paths) {
+    try {
+        const workspaceId = createHash("sha256")
+            .update(root)
+            .digest("hex")
+            .slice(0, 16);
+        const requestedWebPort = input.webPort ?? DEFAULT_WEB_PORT;
+        if (!Number.isSafeInteger(requestedWebPort) ||
+            requestedWebPort < 1 ||
+            requestedWebPort > 65535) {
+            throw new Error(`OPENXIANGDA_LOCAL_WEB_PORT_INVALID:${requestedWebPort}`);
+        }
+        const webPort = input.webPort === undefined
+            ? await availablePort(requestedWebPort)
+            : await requiredPort(requestedWebPort);
+        const appPort = input.uiOnly
+            ? null
+            : await availablePort(DEFAULT_APP_PORT, new Set([webPort]));
+        const platformPort = input.uiOnly
+            ? null
+            : await availablePort(DEFAULT_PLATFORM_PORT, new Set([webPort, appPort].filter((item) => item !== null)));
+        const databasePort = input.uiOnly
+            ? null
+            : await availablePort(DEFAULT_DATABASE_PORT, new Set([webPort, appPort, platformPort].filter((item) => item !== null)));
+        const startedAt = new Date().toISOString();
+        const ownerIdentity = currentProcessIdentity();
+        if (process.platform !== "win32" && !ownerIdentity) {
+            throw new Error("OPENXIANGDA_LOCAL_SESSION_IDENTITY_UNAVAILABLE");
+        }
+        let databaseResetPrepared = false;
+        // Complete non-destructive preflight before honoring reset-then-start.
+        if (input.reset && !input.uiOnly && databaseRuntime.reset) {
+            await databaseRuntime.reset({
+                workspaceId,
+                credentialPath: paths.databaseCredential,
+            });
+            databaseResetPrepared = true;
+        }
+        if (input.reset)
+            rmSync(paths.state, { recursive: true, force: true });
+        mkdirSync(paths.state, { recursive: true, mode: 0o700 });
+        const session = {
+            schemaVersion: 1,
+            workspaceId,
+            root,
+            appCode: input.appCode,
+            mode: "local",
+            uiOnly: input.uiOnly === true,
+            ownerPid: process.pid,
+            ...(ownerIdentity ? { ownerIdentity } : {}),
+            status: "starting",
+            urls: {
+                web: `http://${LOOPBACK_HOST}:${webPort}`,
+                app: appPort === null ? null : `http://${LOOPBACK_HOST}:${appPort}`,
+                platform: platformPort === null
+                    ? `http://${LOOPBACK_HOST}:${webPort}/service`
+                    : `http://${LOOPBACK_HOST}:${platformPort}/service`,
+            },
+            ports: {
+                web: webPort,
+                app: appPort,
+                platform: platformPort,
+                database: databasePort,
+            },
+            database: null,
+            startedAt,
+        };
+        const runtimeOAuthCredential = input.uiOnly
+            ? null
+            : loadOrCreateRuntimeOAuthCredential(paths.oauthCredential, workspaceId, input.appCode, input.runtimeOAuthScopes, input.reset === true);
+        const eventCredential = input.uiOnly
+            ? null
+            : loadOrCreateEventCredential(paths.eventCredential, workspaceId, input.appCode, input.eventSubscriptionCodes, input.reset === true);
+        const localManifest = input.localManifest
+            ? {
+                ...input.localManifest,
+                ...(runtimeOAuthCredential
+                    ? {
+                        runtimeOAuthClient: {
+                            clientId: runtimeOAuthCredential.clientId,
+                            clientSecretHash: runtimeOAuthCredential.clientSecretHash,
+                            scopes: runtimeOAuthCredential.scopes,
+                        },
+                    }
+                    : {}),
+            }
+            : undefined;
+        writeJsonAtomic(paths.lockMetadata, session);
+        writeJsonAtomic(paths.diagnostics, session);
+        if (localManifest)
+            writeJsonAtomic(paths.manifest, localManifest);
+        return {
+            databaseResetPrepared,
+            webPort,
+            appPort,
+            platformPort,
+            databasePort,
+            startedAt,
+            session,
+            runtimeOAuthCredential,
+            eventCredential,
+            localManifest,
+        };
+    }
+    catch (error) {
+        // A failed preflight must not leave a young lock that blocks the next run.
+        rmSync(paths.lockDirectory, { recursive: true, force: true });
+        throw error;
+    }
+}
+function localPaths(root) {
+    const localRoot = join(root, ".openxiangda", "local");
+    return {
+        root: localRoot,
+        lockDirectory: join(localRoot, "dev.lock"),
+        lockMetadata: join(localRoot, "dev.lock", "session.json"),
+        diagnostics: join(localRoot, "diagnostics.json"),
+        logs: join(localRoot, "logs"),
+        log: join(localRoot, "logs", "dev.log"),
+        state: join(localRoot, "state"),
+        databaseCredential: join(localRoot, "state", "postgres.json"),
+        oauthCredential: join(localRoot, "state", "oauth-runtime.json"),
+        eventCredential: join(localRoot, "state", "event-runtime.json"),
+        manifest: join(localRoot, "state", "manifest.json"),
+    };
+}
+function loadOrCreateEventCredential(path, workspaceId, appCode, requestedCodes, reset) {
+    const codes = [...new Set((requestedCodes || []).map(String))].sort();
+    let existing = null;
+    if (!reset && existsSync(path)) {
+        existing = JSON.parse(readFileSync(path, "utf8"));
+        if (existing.schemaVersion !== 1 ||
+            existing.workspaceId !== workspaceId ||
+            existing.appCode !== appCode ||
+            !existing.secrets ||
+            typeof existing.secrets !== "object") {
+            throw new Error("OPENXIANGDA_LOCAL_EVENT_CREDENTIAL_INVALID");
+        }
+    }
+    const secrets = Object.fromEntries(codes.map(code => {
+        if (!/^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/.test(code)) {
+            throw new Error(`OPENXIANGDA_LOCAL_EVENT_CODE_INVALID:${code}`);
+        }
+        const current = existing?.secrets[code];
+        return [
+            code,
+            typeof current === "string" && current.length >= 32
+                ? current
+                : `oxev_local_${randomBytes(32).toString("base64url")}`,
+        ];
+    }));
+    const value = {
+        schemaVersion: 1,
+        workspaceId,
+        appCode,
+        secrets,
+    };
+    if (!existing || JSON.stringify(existing.secrets) !== JSON.stringify(secrets)) {
+        writeJsonAtomic(path, value);
+    }
+    return value;
+}
+function environmentCode(code) {
+    return code.toUpperCase().replace(/[^A-Z0-9]+/g, "_");
+}
+function loadOrCreateRuntimeOAuthCredential(path, workspaceId, appCode, requestedScopes, reset) {
+    const scopes = normalizeRuntimeOAuthScopes(requestedScopes);
+    if (!reset && existsSync(path)) {
+        const value = JSON.parse(readFileSync(path, "utf8"));
+        if (value.schemaVersion !== 1 ||
+            value.workspaceId !== workspaceId ||
+            value.appCode !== appCode ||
+            !/^oxa_runtime_[A-Za-z0-9_-]+$/.test(value.clientId) ||
+            typeof value.clientSecret !== "string" ||
+            value.clientSecret.length < 32 ||
+            !/^scrypt\$[^$]+\$[^$]+$/.test(value.clientSecretHash)) {
+            throw new Error("OPENXIANGDA_LOCAL_OAUTH_CREDENTIAL_INVALID");
+        }
+        if (JSON.stringify(value.scopes) !== JSON.stringify(scopes)) {
+            const next = { ...value, scopes };
+            writeJsonAtomic(path, next);
+            return next;
+        }
+        return value;
+    }
+    const clientSecret = `oxs_local_${randomBytes(32).toString("base64url")}`;
+    const salt = randomBytes(16);
+    const value = {
+        schemaVersion: 1,
+        workspaceId,
+        appCode,
+        clientId: `oxa_runtime_${workspaceId}`,
+        clientSecret,
+        clientSecretHash: `scrypt$${salt.toString("base64url")}$${scryptSync(clientSecret, salt, 32).toString("base64url")}`,
+        scopes,
+    };
+    writeJsonAtomic(path, value);
+    return value;
+}
+function normalizeRuntimeOAuthScopes(scopes) {
+    return [
+        ...new Set([
+            "app:invoke",
+            "data:read",
+            "data:write",
+            "data:transaction",
+            "runtime:lease",
+            "secret:read",
+            ...(scopes || []),
+        ].map(scope => String(scope).trim()).filter(Boolean)),
+    ].sort();
+}
+async function acquireSessionLock(paths, workspaceRoot) {
+    for (let attempt = 0; attempt < 30; attempt += 1) {
+        try {
+            mkdirSync(paths.lockDirectory, { mode: 0o700 });
+            return null;
+        }
+        catch (error) {
+            if (error.code !== "EEXIST")
+                throw error;
+            const existing = readActiveSession(paths.lockMetadata, workspaceRoot);
+            if (existing)
+                return existing;
+            if (!existsSync(paths.lockMetadata) &&
+                Date.now() - statSync(paths.lockDirectory).mtimeMs < 10_000) {
+                await delay(100);
+                continue;
+            }
+            const stale = `${paths.lockDirectory}.stale-${process.pid}-${Date.now()}`;
+            try {
+                renameSync(paths.lockDirectory, stale);
+                rmSync(stale, { recursive: true, force: true });
+            }
+            catch (reclaimError) {
+                if (reclaimError.code !== "ENOENT") {
+                    throw reclaimError;
+                }
+            }
+        }
+    }
+    throw new Error("OPENXIANGDA_LOCAL_LOCK_CONTENTION");
+}
+function readActiveSession(path, expectedRoot) {
+    const session = readSession(path, expectedRoot);
+    if (!session)
+        return null;
+    const ownerMatches = session.ownerIdentity
+        ? processIdentity(session.ownerPid) === session.ownerIdentity
+        : pidIsRunning(session.ownerPid);
+    return ownerMatches && ["starting", "ready"].includes(session.status)
+        ? session
+        : null;
+}
+function readSession(path, expectedRoot) {
+    if (!existsSync(path))
+        return null;
+    try {
+        return readSessionStrict(path, expectedRoot);
+    }
+    catch {
+        return null;
+    }
+}
+function readSessionStrict(path, expectedRoot) {
+    const session = JSON.parse(readFileSync(path, "utf8"));
+    const expectedWorkspaceId = createHash("sha256")
+        .update(expectedRoot)
+        .digest("hex")
+        .slice(0, 16);
+    if (session.schemaVersion !== 1 ||
+        session.root !== expectedRoot ||
+        session.workspaceId !== expectedWorkspaceId ||
+        !Number.isSafeInteger(session.ownerPid) ||
+        session.ownerPid <= 0) {
+        throw new Error("OPENXIANGDA_LOCAL_SESSION_OWNERSHIP_MISMATCH");
+    }
+    return session;
+}
+function assertSessionMetadataIsSafe(paths, expectedRoot) {
+    if (!existsSync(paths.lockMetadata))
+        return;
+    try {
+        readSessionStrict(paths.lockMetadata, expectedRoot);
+    }
+    catch (error) {
+        throw new Error(`OPENXIANGDA_LOCAL_SESSION_OWNERSHIP_MISMATCH: ${error.message}`);
+    }
+}
+function processIdentity(pid) {
+    if (process.platform === "win32")
+        return undefined;
+    const result = spawnSync("ps", ["-p", String(pid), "-o", "lstart=", "-o", "command="], {
+        encoding: "utf8",
+    });
+    if (result.status !== 0)
+        return undefined;
+    const value = String(result.stdout || "").trim();
+    return value ? createHash("sha256").update(value).digest("hex") : undefined;
+}
+function currentProcessIdentity() {
+    return processIdentity(process.pid);
+}
+async function waitForProcessStop(pid, ownerIdentity, timeoutMs) {
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() < deadline) {
+        if (!pidIsRunning(pid))
+            return true;
+        if (ownerIdentity && processIdentity(pid) !== ownerIdentity)
+            return true;
+        await delay(100);
+    }
+    return false;
+}
+function pidIsRunning(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        return error.code === "EPERM";
+    }
+}
+async function availablePort(preferred, excluded = new Set()) {
+    if (!excluded.has(preferred) && (await portIsAvailable(preferred))) {
+        return preferred;
+    }
+    for (let attempt = 0; attempt < 20; attempt += 1) {
+        const port = await ephemeralPort();
+        if (!excluded.has(port))
+            return port;
+    }
+    throw new Error("OPENXIANGDA_LOCAL_PORT_ALLOCATION_FAILED");
+}
+async function requiredPort(port) {
+    if (await portIsAvailable(port))
+        return port;
+    throw new Error(`OPENXIANGDA_LOCAL_WEB_PORT_IN_USE:${port}`);
+}
+function ephemeralPort() {
+    return new Promise((resolve, reject) => {
+        const server = createServer();
+        server.unref();
+        server.once("error", reject);
+        server.listen({ host: LOOPBACK_HOST, port: 0, exclusive: true }, () => {
+            const address = server.address();
+            const port = typeof address === "object" && address ? address.port : 0;
+            server.close(error => (error ? reject(error) : resolve(port)));
+        });
+    });
+}
+async function portIsAvailable(port) {
+    return await new Promise(resolve => {
+        const server = createServer();
+        server.unref();
+        server.once("error", () => resolve(false));
+        server.listen({ host: LOOPBACK_HOST, port, exclusive: true }, () => {
+            server.close(() => resolve(true));
+        });
+    });
+}
+async function waitForLocalReadiness(session, children, timeoutMs = 120_000) {
+    const urls = [
+        session.urls.web,
+        `${session.urls.platform}/openxiangda-api/v2/capabilities`,
+        ...(session.urls.app
+            ? [`${session.urls.app}/__platform/ready`]
+            : []),
+    ];
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() < deadline) {
+        const exited = children.find(child => child.exitCode !== null);
+        if (exited) {
+            throw new Error(`OPENXIANGDA_LOCAL_PROCESS_EXITED: ${exited.exitCode}`);
+        }
+        const checks = await Promise.all(urls.map(url => httpReady(url)));
+        if (checks.every(Boolean))
+            return;
+        await delay(200);
+    }
+    throw new Error(`OPENXIANGDA_LOCAL_READINESS_TIMEOUT: ${urls.join(", ")}`);
+}
+async function httpReady(url) {
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), 1_000);
+    try {
+        const response = await fetch(url, { signal: controller.signal });
+        return response.ok;
+    }
+    catch {
+        return false;
+    }
+    finally {
+        clearTimeout(timeout);
+    }
+}
+function childExit(child) {
+    return new Promise(resolve => {
+        let spawnError;
+        child.once("error", error => {
+            spawnError = error;
+        });
+        child.once("close", (code, signal) => {
+            resolve({
+                code: code ?? (signal ? 0 : 1),
+                ...(spawnError ? { error: spawnError } : {}),
+            });
+        });
+    });
+}
+function terminateChild(child, signal) {
+    if (!child?.pid || child.exitCode !== null)
+        return;
+    try {
+        if (process.platform === "win32") {
+            spawn("taskkill", ["/pid", String(child.pid), "/t", "/f"], {
+                detached: true,
+                stdio: "ignore",
+            }).unref();
+        }
+        else {
+            process.kill(-child.pid, signal);
+        }
+    }
+    catch {
+        try {
+            child.kill(signal);
+        }
+        catch {
+            // The child already exited between the status check and termination.
+        }
+    }
+}
+function terminateChildren(children, signal) {
+    for (const child of children)
+        terminateChild(child, signal);
+}
+async function waitForChildrenExit(children, exits) {
+    if (exits.length === 0)
+        return [];
+    const completed = Promise.all(exits);
+    const exited = await Promise.race([
+        completed.then(() => true),
+        delay(5_000).then(() => false),
+    ]);
+    if (!exited) {
+        terminateChildren(children, "SIGKILL");
+        return await Promise.race([completed, delay(1_000).then(() => [])]);
+    }
+    return await completed;
+}
+function pipeOutput(source, target, log) {
+    if (!source)
+        return;
+    source.on("data", chunk => {
+        target.write(chunk);
+        log.write(chunk);
+    });
+}
+function writeJsonAtomic(path, value) {
+    const temporary = `${path}.${process.pid}.tmp`;
+    writeFileSync(temporary, `${JSON.stringify(value, null, 2)}\n`, {
+        encoding: "utf8",
+        mode: 0o600,
+    });
+    renameSync(temporary, path);
+}
+function openBrowser(url) {
+    const command = process.platform === "darwin"
+        ? { file: "open", args: [url] }
+        : process.platform === "win32"
+            ? { file: "cmd", args: ["/c", "start", "", url] }
+            : { file: "xdg-open", args: [url] };
+    try {
+        const child = spawn(command.file, command.args, {
+            detached: true,
+            stdio: "ignore",
+        });
+        child.on("error", () => undefined);
+        child.unref();
+    }
+    catch {
+        // The URL is always printed, so headless environments remain usable.
+    }
+}
+function delay(milliseconds) {
+    return new Promise(resolve => setTimeout(resolve, milliseconds));
+}
+//# sourceMappingURL=local-development.js.map