@fecommunity/reactpress 4.0.0-beta.0 → 4.0.0-beta.10

package/out/lib/menu-actions.js

@@ -0,0 +1,418 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+// @ts-nocheck
+const fs = require('fs');
+const path = require('path');
+const inquirer = require('inquirer');
+const ora = require('ora');
+const open = require('open');
+const { brand, ok, fail, sectionHeader, statusPill, padRight } = require('../ui/theme');
+const { describeProject } = require('./project-type');
+const { hasResolvableActiveTheme } = require('./theme-runtime');
+const { ensureProjectEnvironment, initMonorepoProject } = require('./bootstrap');
+const { runDefaultDev, runDockerDev, runThemeDev, runWebDev, runLocalWebDev, runDesktopDev, enableLocalDevMode } = require('./dev');
+const { runApiDev } = require('./api-dev');
+const { runLifecycleCommand } = require('./lifecycle');
+const { runDockerCommand } = require('./docker');
+const { runNginxCommand } = require('./nginx');
+const { printUnifiedStatus } = require('./status');
+const { runDoctor } = require('./doctor');
+const { runDbBackup } = require('./db-backup');
+const { runBuild, TARGETS } = require('./build');
+const { loadClientSiteUrl, loadServerSiteUrl, isHttpResponding } = require('./http');
+const { isDockerRunning } = require('./docker');
+const { enableInkDashboard } = require('./cli-events');
+const { t } = require('./i18n');
+function choice(labelKey, value, hintKey, slashExtra = []) {
+    const parts = value.split(/[:/]/).filter(Boolean);
+    const slash = [...new Set([value, ...parts, ...slashExtra])];
+    return {
+        label: t(labelKey),
+        hint: hintKey ? t(hintKey) : '',
+        value,
+        slash,
+    };
+}
+function getMenuSections(project) {
+    const standalone = project.type === 'standalone';
+    const monorepo = project.type === 'monorepo';
+    const showTheme = hasResolvableActiveTheme(project.root);
+    const sections = [
+        {
+            title: t('menu.section.start'),
+            items: [
+                choice('menu.dev', 'dev', 'menu.hint.dev', ['start', 'run']),
+                choice('menu.init', 'init', 'menu.hint.init', ['setup']),
+                choice('menu.status', 'status', 'menu.hint.status', ['info']),
+                choice('menu.doctor', 'doctor', 'menu.hint.doctor', ['check', 'diag']),
+            ],
+        },
+    ];
+    const devItems = [choice('menu.devApi', 'dev:api', 'menu.hint.devApi', ['api'])];
+    if (showTheme) {
+        devItems.push(choice('menu.devClient', 'dev:client', 'menu.hint.devClient'));
+    }
+    if (project.hasDesktop) {
+        devItems.push(choice('menu.devDesktop', 'dev:desktop', 'menu.hint.devDesktop'));
+    }
+    if (project.hasWeb) {
+        devItems.push(choice('menu.devWeb', 'dev:web', 'menu.hint.devWeb'));
+        devItems.push(choice('menu.devLocalWeb', 'dev:local-web', 'menu.hint.devLocalWeb'));
+    }
+    sections.push({ title: t('menu.section.dev'), items: devItems });
+    const projectItems = [
+        choice('menu.initLocal', 'init:local', 'menu.hint.initLocal'),
+        choice('menu.themeList', 'theme:list', 'menu.hint.themeList'),
+    ];
+    if (monorepo && project.hasPluginsWorkspace) {
+        projectItems.push(choice('menu.pluginList', 'plugin:list', 'menu.hint.pluginList'));
+    }
+    sections.push({ title: t('menu.section.project'), items: projectItems });
+    sections.push({
+        title: t('menu.section.server'),
+        items: [
+            choice('menu.serverStart', 'server:start', 'menu.hint.serverStart'),
+            choice('menu.serverStop', 'server:stop', 'menu.hint.serverStop'),
+            choice('menu.serverRestart', 'server:restart', 'menu.hint.serverRestart'),
+        ],
+    });
+    const buildItems = [choice('menu.build', 'build', 'menu.hint.build', ['compile'])];
+    if (monorepo) {
+        buildItems.push(choice('menu.dockerStart', 'docker:start', 'menu.hint.dockerStart'), choice('menu.dockerUp', 'docker:up', 'menu.hint.dockerUp'), choice('menu.dockerStop', 'docker:stop', 'menu.hint.dockerStop'));
+    }
+    else if (standalone) {
+        buildItems.push(choice('menu.dockerUp', 'docker:up', 'menu.hint.dockerUp'), choice('menu.dockerStop', 'docker:stop', 'menu.hint.dockerStop'));
+    }
+    sections.push({ title: t('menu.section.build'), items: buildItems });
+    const toolItems = [
+        choice('menu.nginxUp', 'nginx:up', 'menu.hint.nginxUp'),
+        choice('menu.nginxOpen', 'nginx:open', 'menu.hint.nginxOpen'),
+        choice('menu.nginxReload', 'nginx:reload', 'menu.hint.nginxReload'),
+        choice('menu.dbBackup', 'db:backup', 'menu.hint.dbBackup'),
+        choice('menu.openAdmin', 'open:admin', 'menu.hint.openAdmin'),
+    ];
+    if (monorepo) {
+        toolItems.push(choice('menu.publish', 'publish', 'menu.hint.publish'));
+    }
+    sections.push({ title: t('menu.section.tools'), items: toolItems });
+    sections.push({
+        title: '',
+        items: [choice('menu.exit', 'exit', 'menu.hint.exit', ['quit', 'q'])],
+    });
+    return sections;
+}
+/** Flat menu list with numeric shortcuts 1–9 for the first nine actionable items. */
+function flattenMenuSections(sections) {
+    const flat = [];
+    let shortcut = 0;
+    for (const section of sections) {
+        flat.push({ type: 'section', title: section.title });
+        for (const item of section.items) {
+            shortcut += 1;
+            flat.push({
+                type: 'item',
+                ...item,
+                shortcut: shortcut <= 9 ? String(shortcut) : '',
+            });
+        }
+    }
+    return flat;
+}
+function getMenuActions(project) {
+    return flattenMenuSections(getMenuSections(project));
+}
+function parseEnvFile(projectRoot) {
+    const envPath = path.join(projectRoot, '.env');
+    const env = {};
+    try {
+        if (!fs.existsSync(envPath))
+            return env;
+        for (const line of fs.readFileSync(envPath, 'utf8').split('\n')) {
+            const m = line.match(/^([A-Z_]+)=(.*)$/);
+            if (m)
+                env[m[1]] = m[2].trim().replace(/^['"]|['"]$/g, '');
+        }
+    }
+    catch {
+        // ignore
+    }
+    return env;
+}
+async function probeDatabase(projectRoot) {
+    try {
+        const mysql = require('mysql2/promise');
+        const env = parseEnvFile(projectRoot);
+        const conn = await mysql.createConnection({
+            host: env.DB_HOST || '127.0.0.1',
+            port: Number(env.DB_PORT || 3306),
+            user: env.DB_USER || 'reactpress',
+            password: env.DB_PASSWD || env.DB_PASSWORD || 'reactpress',
+            database: env.DB_DATABASE || 'reactpress',
+            connectTimeout: 2000,
+        });
+        await conn.ping();
+        await conn.end();
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function fetchContextStatus(projectRoot) {
+    const apiUrl = loadServerSiteUrl(projectRoot);
+    const [apiOk, dockerOk, dbOk] = await Promise.all([
+        isHttpResponding(apiUrl, 1500),
+        Promise.resolve(isDockerRunning()),
+        probeDatabase(projectRoot),
+    ]);
+    return { apiOk, dbOk, dockerOk };
+}
+function printStatusPanel(status) {
+    const on = { on: t('menu.statusOn'), off: t('menu.statusOff') };
+    const db = {
+        on: t('menu.statusReady'),
+        off: t('menu.statusNotReady'),
+        pending: t('menu.statusChecking'),
+    };
+    const docker = { on: t('menu.statusYes'), off: t('menu.statusNo') };
+    console.log(sectionHeader(t('menu.statusHeader')));
+    const rows = [
+        [t('menu.statusLabelApi'), statusPill(status.apiOk, on)],
+        [t('menu.statusLabelDb'), statusPill(status.dbOk, db)],
+        [t('menu.statusLabelDocker'), statusPill(status.dockerOk, docker)],
+    ];
+    for (const [name, pill] of rows) {
+        console.log(`  ${brand.muted(padRight(name, 10))}  ${pill}`);
+    }
+    console.log('');
+}
+async function printContextStatus(projectRoot) {
+    const spinner = ora({
+        text: brand.dim(t('menu.statusChecking')),
+        color: 'magenta',
+        spinner: 'dots',
+    }).start();
+    const status = await fetchContextStatus(projectRoot);
+    spinner.stop();
+    printStatusPanel(status);
+    return status;
+}
+async function withSpinner(text, fn) {
+    const spinner = ora({ text, color: 'magenta', spinner: 'dots' }).start();
+    try {
+        const result = await fn();
+        spinner.succeed();
+        return result;
+    }
+    catch (err) {
+        spinner.fail();
+        throw err;
+    }
+}
+const LONG_RUNNING_ACTIONS = new Set([
+    'dev',
+    'dev:api',
+    'dev:client',
+    'dev:desktop',
+    'dev:web',
+    'dev:local-web',
+    'docker:start',
+]);
+function isLongRunningAction(action) {
+    return LONG_RUNNING_ACTIONS.has(action);
+}
+async function pickBuildTargetInteractive() {
+    const buildChoices = TARGETS.map((target) => ({
+        name: target === 'all' ? t('menu.buildAll') : t(`build.label.${target}`),
+        value: target,
+    }));
+    const { target } = await inquirer.prompt([
+        {
+            type: 'list',
+            name: 'target',
+            message: t('menu.buildTarget'),
+            pageSize: 12,
+            choices: buildChoices,
+        },
+    ]);
+    return target;
+}
+async function runMenuAction(action, projectRoot, project, options = {}) {
+    const { selectBuildTarget, useInkDashboard = false, onLegacyOutput } = options;
+    switch (action) {
+        case 'dev':
+            if (useInkDashboard)
+                enableInkDashboard();
+            await runDefaultDev(projectRoot);
+            return false;
+        case 'init': {
+            const result = await withSpinner(t('menu.initProject'), () => ensureProjectEnvironment(projectRoot));
+            console.log(ok(result.message || t('menu.done')));
+            return true;
+        }
+        case 'status':
+            if (onLegacyOutput) {
+                await onLegacyOutput(() => printUnifiedStatus(projectRoot));
+                return true;
+            }
+            await printUnifiedStatus(projectRoot);
+            return true;
+        case 'doctor': {
+            if (onLegacyOutput) {
+                await onLegacyOutput(async () => {
+                    const code = await runDoctor(projectRoot);
+                    if (code !== 0)
+                        process.exit(code);
+                });
+                return true;
+            }
+            const code = await runDoctor(projectRoot);
+            if (code !== 0)
+                process.exit(code);
+            return true;
+        }
+        case 'dev:api':
+            if (useInkDashboard)
+                enableInkDashboard();
+            await runApiDev(projectRoot);
+            return false;
+        case 'dev:client':
+            if (useInkDashboard)
+                enableInkDashboard();
+            await runThemeDev(projectRoot);
+            return false;
+        case 'dev:desktop':
+            if (useInkDashboard)
+                enableInkDashboard();
+            await runDesktopDev(projectRoot);
+            return false;
+        case 'dev:web':
+            if (useInkDashboard)
+                enableInkDashboard();
+            await runWebDev(projectRoot);
+            return false;
+        case 'dev:local-web':
+            enableLocalDevMode();
+            if (useInkDashboard)
+                enableInkDashboard();
+            await runLocalWebDev(projectRoot);
+            return false;
+        case 'init:local': {
+            const { isMonorepoCheckout } = require('./root');
+            const { initProject } = require('../core/services/init');
+            const result = await withSpinner(t('menu.initProject'), async () => {
+                if (isMonorepoCheckout(projectRoot)) {
+                    return initMonorepoProject(projectRoot, { local: true });
+                }
+                return initProject({ directory: projectRoot, force: false, local: true });
+            });
+            console.log(ok(result.message || t('menu.done')));
+            return true;
+        }
+        case 'theme:list':
+            if (onLegacyOutput) {
+                await onLegacyOutput(() => require('./theme-cli').runThemeList(projectRoot));
+                return true;
+            }
+            require('./theme-cli').runThemeList(projectRoot);
+            return true;
+        case 'plugin:list':
+            if (onLegacyOutput) {
+                await onLegacyOutput(() => require('./plugin-cli').runPluginList(projectRoot));
+                return true;
+            }
+            require('./plugin-cli').runPluginList(projectRoot);
+            return true;
+        case 'db:backup':
+            await withSpinner(t('cli.db.backup'), async () => {
+                await runDbBackup(projectRoot);
+            });
+            return true;
+        case 'server:start': {
+            const code = await withSpinner(t('menu.startingApi'), () => runLifecycleCommand('start', projectRoot));
+            if (code !== 0)
+                process.exit(code);
+            return true;
+        }
+        case 'server:stop':
+            await withSpinner(t('menu.stoppingApi'), async () => {
+                await runLifecycleCommand('stop', projectRoot);
+            });
+            return true;
+        case 'server:restart': {
+            const code = await withSpinner(t('menu.restartingApi'), () => runLifecycleCommand('restart', projectRoot));
+            if (code !== 0)
+                process.exit(code);
+            return true;
+        }
+        case 'build': {
+            const target = selectBuildTarget
+                ? await selectBuildTarget()
+                : await pickBuildTargetInteractive();
+            if (onLegacyOutput) {
+                await onLegacyOutput(() => runBuild(target, projectRoot));
+                return true;
+            }
+            await runBuild(target, projectRoot);
+            return true;
+        }
+        case 'docker:start':
+            await runDockerCommand('start', projectRoot);
+            return false;
+        case 'docker:up':
+            await withSpinner(t('docker.starting'), () => runDockerCommand('up', projectRoot));
+            return true;
+        case 'docker:stop':
+            await withSpinner(t('docker.stopping'), async () => {
+                await runDockerCommand('down', projectRoot);
+            });
+            return true;
+        case 'nginx:up':
+            await withSpinner(t('cli.nginx.up'), async () => {
+                await runNginxCommand('up', projectRoot);
+            });
+            return true;
+        case 'nginx:open':
+            await runNginxCommand('open', projectRoot);
+            return true;
+        case 'nginx:reload':
+            await runNginxCommand('reload', projectRoot);
+            return true;
+        case 'open:admin': {
+            const url = loadClientSiteUrl(projectRoot);
+            console.log(`${brand.primary('›')} ${t('menu.opening', { url })}`);
+            await open(url);
+            return true;
+        }
+        case 'publish': {
+            const prev = process.argv.slice();
+            process.argv = [process.argv[0], process.argv[1], '--publish'];
+            if (onLegacyOutput) {
+                await onLegacyOutput(() => require('./publish').main());
+            }
+            else {
+                await require('./publish').main();
+            }
+            process.argv = prev;
+            return true;
+        }
+        case 'exit':
+            return false;
+        default:
+            return true;
+    }
+}
+module.exports = {
+    TARGETS,
+    choice,
+    getMenuSections,
+    getMenuActions,
+    flattenMenuSections,
+    fetchContextStatus,
+    printStatusPanel,
+    printContextStatus,
+    runMenuAction,
+    isLongRunningAction,
+    pickBuildTargetInteractive,
+};
+//# sourceMappingURL=menu-actions.js.map

package/out/lib/nginx.js

@@ -59,11 +59,14 @@ function readDevNginxPorts(projectRoot) {
     };
 }
 function resolveRemoteUpstreamHost(remoteApiOrigin) {
+    const raw = typeof remoteApiOrigin === 'string' ? remoteApiOrigin.trim() : '';
+    if (!raw)
+        return '';
     try {
-        return new URL(remoteApiOrigin).host;
+        return new URL(raw).host;
     }
     catch {
-        return remoteApiOrigin.replace(/^https?:\/\//i, '').split('/')[0];
+        return raw.replace(/^https?:\/\//i, '').split('/')[0];
     }
 }
 function renderApiProxyBlock(remoteApiOrigin, apiPort) {

package/out/lib/paths.js

@@ -28,6 +28,16 @@ function getCliPackageRoot() {
         return path.dirname(require.resolve('@fecommunity/reactpress-cli/package.json'));
     }
 }
+function getCliVersion() {
+    try {
+        const pkgPath = path.join(getCliPackageRoot(), 'package.json');
+        const pkg = require(pkgPath);
+        return typeof pkg.version === 'string' ? pkg.version : 'dev';
+    }
+    catch {
+        return 'dev';
+    }
+}
 function getBundledServerDir() {
     return path.join(getCliPackageRoot(), 'server');
 }
@@ -94,6 +104,7 @@ module.exports = {
     isUsingMonorepoServer,
     canStartLocalApi,
     getCliPackageRoot,
+    getCliVersion,
     getBundledServerDir,
     getServerDir,
     getServerBin,

package/out/lib/pm2.js

@@ -2,10 +2,17 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 // @ts-nocheck
 const { spawn } = require('child_process');
-const { getServerBin, getServerDir } = require('./paths');
+const { getServerBin, getServerDir, isUsingMonorepoServer } = require('./paths');
 const { ensureOriginalCwd } = require('./root');
 const { t } = require('./i18n');
-function startApiWithPm2(projectRoot = ensureOriginalCwd()) {
+const { ensureBundledServerDeps } = require('./server-bundle');
+async function startApiWithPm2(projectRoot = ensureOriginalCwd()) {
+    if (!isUsingMonorepoServer(projectRoot)) {
+        const bundled = await ensureBundledServerDeps(projectRoot);
+        if (!bundled.ok) {
+            throw new Error(bundled.message || t('bundle.serverBundle.notBuilt'));
+        }
+    }
     return new Promise((resolve, reject) => {
         const child = spawn(process.execPath, [getServerBin(projectRoot), '--pm2'], {
             stdio: 'inherit',

package/out/lib/ports.js

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 // @ts-nocheck
 const fs = require('fs');
 const path = require('path');
+const net = require('net');
 const { spawnSync } = require('child_process');
 /**
  * Local dev port map (keep in sync with `.env`, README, and `theme.service.ts` defaults).
@@ -22,6 +23,84 @@ const DEV_PORTS = {
     THEME_PREVIEW: 3003,
     MYSQL: 3306,
 };
+/** Offset applied per `REACTPRESS_INSTANCE` (instance 1 → admin :3010, api :3012, …). */
+const INSTANCE_PORT_STEP = 10;
+function readProcessEnvPort(key) {
+    const raw = process.env[key]?.trim();
+    if (!raw)
+        return null;
+    const n = parseInt(raw.replace(/^['"]|['"]$/g, ''), 10);
+    return Number.isInteger(n) && n > 0 ? n : null;
+}
+function readInstanceIndex() {
+    const raw = process.env.REACTPRESS_INSTANCE ?? process.env.REACTPRESS_DEV_INSTANCE ?? '0';
+    const n = parseInt(String(raw).trim(), 10);
+    if (!Number.isInteger(n) || n < 0 || n > 99)
+        return 0;
+    return n;
+}
+function instancePortOffset() {
+    return readInstanceIndex() * INSTANCE_PORT_STEP;
+}
+/**
+ * Resolve a dev-stack port: process.env override → `.env` (instance 0 only) → default + instance offset.
+ */
+function resolveStackPort(projectRoot, envKey, defaultBase) {
+    const fromProcess = readProcessEnvPort(envKey);
+    if (fromProcess)
+        return fromProcess;
+    const instance = readInstanceIndex();
+    const shiftedDefault = defaultBase + instance * INSTANCE_PORT_STEP;
+    if (instance === 0) {
+        try {
+            const content = fs.readFileSync(path.join(projectRoot, '.env'), 'utf8');
+            const match = content.match(new RegExp(`^${envKey}=(.+)$`, 'm'));
+            if (match) {
+                const n = parseInt(match[1].trim().replace(/^['"]|['"]$/g, ''), 10);
+                if (Number.isInteger(n) && n > 0)
+                    return n;
+            }
+        }
+        catch {
+            // ignore
+        }
+    }
+    return shiftedDefault;
+}
+function resolveDevStackPorts(projectRoot) {
+    const offset = instancePortOffset();
+    const visitorFromProcess = readProcessEnvPort('CLIENT_PORT');
+    let visitor = DEV_PORTS.VISITOR + offset;
+    if (visitorFromProcess) {
+        visitor = visitorFromProcess;
+    }
+    else if (readInstanceIndex() === 0) {
+        visitor = readVisitorPort(projectRoot);
+    }
+    return {
+        admin: resolveStackPort(projectRoot, 'WEB_ADMIN_PORT', DEV_PORTS.ADMIN_WEB),
+        visitor,
+        api: resolveStackPort(projectRoot, 'SERVER_PORT', DEV_PORTS.API),
+        preview: resolveStackPort(projectRoot, 'REACTPRESS_PREVIEW_PORT', DEV_PORTS.THEME_PREVIEW),
+    };
+}
+/** Push resolved ports into `process.env` so child processes share one port map. */
+function applyDevStackPortsToEnv(ports) {
+    process.env.WEB_ADMIN_PORT = String(ports.admin);
+    process.env.SERVER_PORT = String(ports.api);
+    process.env.REACTPRESS_LOCAL_API_PORT = String(ports.api);
+    process.env.CLIENT_PORT = String(ports.visitor);
+    process.env.REACTPRESS_PREVIEW_PORT = String(ports.preview);
+    process.env.CLIENT_SITE_URL = `http://localhost:${ports.visitor}`;
+    process.env.SERVER_SITE_URL = `http://127.0.0.1:${ports.api}`;
+    if (!process.env.VITE_DEV_API_PROXY_TARGET?.trim()) {
+        process.env.VITE_DEV_API_PROXY_TARGET = `http://127.0.0.1:${ports.api}`;
+    }
+}
+function devSessionSuffix() {
+    const instance = readInstanceIndex();
+    return instance > 0 ? `-instance-${instance}` : '';
+}
 /** Ports theme `next dev` must not bind to (reserved for other services). 3003 is allowed — preview theme. */
 /** Never kill listeners on DB / infra ports during dev port cleanup. */
 const PROTECTED_KILL_PORTS = new Set([3306, 3307, 5432, 6379]);
@@ -40,6 +119,9 @@ const BLOCKED_THEME_DEV_PORTS = new Set([
     3307,
 ]);
 function readEnvPort(projectRoot, key, fallback) {
+    const fromProcess = readProcessEnvPort(key);
+    if (fromProcess)
+        return fromProcess;
     try {
         const content = fs.readFileSync(path.join(projectRoot, '.env'), 'utf8');
         const match = content.match(new RegExp(`^${key}=(.+)$`, 'm'));
@@ -289,18 +371,16 @@ async function releaseStaleDevStackPorts(projectRoot) {
         return;
     }
     const { getHealthUrl, checkHealth } = require('./http');
-    // Embedded desktop SQLite API (:13102) is managed by local-server — not SERVER_PORT (:3002).
-    if (process.env.REACTPRESS_DESKTOP_LOCAL !== '1') {
-        const apiPort = readEnvPort(projectRoot, 'SERVER_PORT', DEV_PORTS.API);
-        if (isPortListening(apiPort)) {
-            const health = await checkHealth(getHealthUrl(projectRoot), 2000);
-            if (health.ok) {
-                const { logDevDetail } = require('./dev-log');
-                logDevDetail('dev.apiKept', { port: apiPort });
-            }
-            else {
-                await forceReleaseApiPort(projectRoot);
-            }
+    const apiPort = resolveStackPort(projectRoot, 'SERVER_PORT', DEV_PORTS.API);
+    if (isPortListening(apiPort)) {
+        const healthUrl = `http://127.0.0.1:${apiPort}/api/health`;
+        const health = await checkHealth(healthUrl, 2000);
+        if (health.ok) {
+            const { logDevDetail } = require('./dev-log');
+            logDevDetail('dev.apiKept', { port: apiPort });
+        }
+        else {
+            await stopApiPortListeners(projectRoot, apiPort);
         }
     }
     const previewPort = readEnvPort(projectRoot, 'REACTPRESS_PREVIEW_PORT', DEV_PORTS.THEME_PREVIEW);
@@ -333,7 +413,7 @@ async function ensurePortFree(port, { label = 'service', maxWaitMs = 8000 } = {}
         const desktopApi = process.env.REACTPRESS_DESKTOP_LOCAL_API?.trim();
         if (desktopApi) {
             try {
-                const desktopPort = parseInt(new URL(desktopApi).port || '13102', 10);
+                const desktopPort = parseInt(new URL(desktopApi).port || String(DEV_PORTS.API), 10);
                 if (Number.isInteger(desktopPort) && desktopPort === n) {
                     if (isPortListening(n)) {
                         console.warn(`[reactpress] Port ${n} (${label}) is the embedded local API — leaving listener`);
@@ -364,6 +444,39 @@ async function ensurePortFree(port, { label = 'service', maxWaitMs = 8000 } = {}
     }
     return true;
 }
+function isPortBindable(port) {
+    return new Promise((resolve) => {
+        const server = net.createServer();
+        server.once('error', () => resolve(false));
+        server.once('listening', () => {
+            server.close(() => resolve(true));
+        });
+        server.listen(port, '127.0.0.1');
+    });
+}
+/**
+ * Pick an API port: reuse healthy listener, else preferred, else next free slot in range.
+ * @returns {{ port: number, reused: boolean, shifted?: boolean }}
+ */
+async function resolveApiPortForBind(projectRoot, { preferred } = {}) {
+    const start = preferred ?? resolveStackPort(projectRoot, 'SERVER_PORT', DEV_PORTS.API);
+    const healthUrl = `http://127.0.0.1:${start}/api/health`;
+    const { checkHealth } = require('./http');
+    const health = await checkHealth(healthUrl, 1500);
+    if (health.ok) {
+        return { port: start, reused: true };
+    }
+    if (!isPortListening(start)) {
+        return { port: start, reused: false };
+    }
+    for (let port = start; port < start + 20; port += 1) {
+        if (!isPortListening(port) && (await isPortBindable(port))) {
+            console.warn(`[reactpress] API port ${start} is busy — using :${port}`);
+            return { port, reused: false, shifted: true };
+        }
+    }
+    throw new Error(`No available API port near ${start} (set SERVER_PORT or REACTPRESS_INSTANCE)`);
+}
 /** Free theme/admin ports (API handled in {@link forceReleaseDevStackPorts} / {@link spawnApi}). */
 async function ensureDevStackPorts(projectRoot) {
     const previewPort = readEnvPort(projectRoot, 'REACTPRESS_PREVIEW_PORT', DEV_PORTS.THEME_PREVIEW);
@@ -379,9 +492,17 @@ async function ensureDevStackPorts(projectRoot) {
 }
 module.exports = {
     DEV_PORTS,
+    INSTANCE_PORT_STEP,
     BLOCKED_THEME_DEV_PORTS,
     readEnvPort,
     readVisitorPort,
+    readInstanceIndex,
+    instancePortOffset,
+    resolveStackPort,
+    resolveDevStackPorts,
+    applyDevStackPortsToEnv,
+    resolveApiPortForBind,
+    devSessionSuffix,
     isPortListening,
     killPortListeners,
     ensurePortFree,