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

package/out/lib/context-status.js

@@ -0,0 +1,154 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+// @ts-nocheck
+const fs = require('fs');
+const path = require('path');
+const { describeProject } = require('./project-type');
+const { isDockerRunning } = require('./docker');
+const { isNginxContainerRunning } = require('./nginx');
+const { DEV_PORTS, readEnvPort, isPortListening, } = require('./ports');
+const { loadServerSiteUrl, loadWebAdminUrl, loadAdminConsoleUrl, isHttpResponding, checkHealth, getHealthUrl, } = require('./http');
+const SERVICE_ORDER = ['sqlite', 'mysql', 'server', 'docker', 'nginx', 'web'];
+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 resolveDbType(projectRoot) {
+    try {
+        const { resolveDatabaseProfile } = require('../core/services/database/profile');
+        const profile = await resolveDatabaseProfile(projectRoot);
+        return profile.type;
+    }
+    catch {
+        const env = parseEnvFile(projectRoot);
+        if (String(env.DB_TYPE || '').toLowerCase() === 'sqlite')
+            return 'sqlite';
+        try {
+            const configPath = path.join(projectRoot, '.reactpress/config.json');
+            if (fs.existsSync(configPath)) {
+                const config = JSON.parse(fs.readFileSync(configPath, 'utf8'));
+                if (config.database && config.database.mode === 'embedded-sqlite')
+                    return 'sqlite';
+            }
+        }
+        catch {
+            // ignore
+        }
+        return 'mysql';
+    }
+}
+async function probeMysql(projectRoot) {
+    const port = readEnvPort(projectRoot, 'DB_PORT', DEV_PORTS.MYSQL);
+    if (isPortListening(port))
+        return true;
+    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 || DEV_PORTS.MYSQL),
+            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 probeSqlite(projectRoot) {
+    const { probeSqliteDatabase } = require('../core/services/database/sqlite');
+    const result = await probeSqliteDatabase(projectRoot);
+    return result.ok;
+}
+async function probeServer(projectRoot) {
+    const port = readEnvPort(projectRoot, 'SERVER_PORT', DEV_PORTS.API);
+    if (isPortListening(port))
+        return true;
+    const [httpOk, health] = await Promise.all([
+        isHttpResponding(loadServerSiteUrl(projectRoot), 1500),
+        checkHealth(getHealthUrl(projectRoot)),
+    ]);
+    return httpOk || health.ok;
+}
+async function probeWeb(projectRoot) {
+    if (process.env.REACTPRESS_LOCAL_MODE === '1' || process.env.REACTPRESS_SKIP_NGINX === '1') {
+        return isHttpResponding(loadAdminConsoleUrl(projectRoot), 1500);
+    }
+    const port = readEnvPort(projectRoot, 'WEB_ADMIN_PORT', DEV_PORTS.ADMIN_WEB);
+    if (isPortListening(port))
+        return true;
+    return isHttpResponding(loadWebAdminUrl(projectRoot), 1500);
+}
+function resolveServiceChecks(dbType) {
+    const dbId = dbType === 'sqlite' ? 'sqlite' : 'mysql';
+    if (dbType === 'sqlite') {
+        return [dbId, 'server', 'web'];
+    }
+    return [dbId, 'server', 'web'];
+}
+async function probeService(projectRoot, id) {
+    switch (id) {
+        case 'sqlite':
+            return probeSqlite(projectRoot);
+        case 'mysql':
+            return probeMysql(projectRoot);
+        case 'server':
+            return probeServer(projectRoot);
+        case 'docker':
+            return Promise.resolve(isDockerRunning());
+        case 'nginx':
+            return Promise.resolve(isNginxContainerRunning());
+        case 'web':
+            return probeWeb(projectRoot);
+        default:
+            return false;
+    }
+}
+async function emitProgress(onProgress, payload) {
+    if (!onProgress)
+        return;
+    onProgress(payload);
+    await new Promise((resolve) => setImmediate(resolve));
+}
+async function fetchContextStatus(projectRoot, { onProgress } = {}) {
+    const project = describeProject(projectRoot);
+    await emitProgress(onProgress, { phase: 'start', id: '__config' });
+    const dbType = await resolveDbType(projectRoot);
+    const ids = resolveServiceChecks(dbType);
+    await emitProgress(onProgress, { phase: 'ready', total: ids.length + 1 });
+    await emitProgress(onProgress, { phase: 'done', id: '__config' });
+    const components = await Promise.all(ids.map(async (id) => {
+        await emitProgress(onProgress, { phase: 'start', id });
+        const ok = await probeService(projectRoot, id);
+        await emitProgress(onProgress, { phase: 'done', id, ok });
+        return { id, ok };
+    }));
+    return { components, project, dbType };
+}
+module.exports = {
+    fetchContextStatus,
+    resolveServiceChecks,
+    resolveDbType,
+    parseEnvFile,
+    probeService,
+    SERVICE_ORDER,
+};
+//# sourceMappingURL=context-status.js.map

package/out/lib/create-site.js

@@ -0,0 +1,187 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createSite = createSite;
+// @ts-nocheck
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const node_child_process_1 = require("node:child_process");
+const local_site_1 = require("../core/services/local-site");
+const paths_1 = require("./paths");
+const i18n_1 = require("./i18n");
+const THEME_RUNTIME_REL = node_path_1.default.join('.reactpress', 'runtime', 'hello-world');
+const ACTIVE_THEME_MANIFEST_REL = node_path_1.default.join('.reactpress', 'active-theme.json');
+const THEME_COPY_SKIP = new Set([
+    'node_modules',
+    '.next',
+    '.git',
+    'coverage',
+    '.turbo',
+    '.cache',
+    'package-lock.json',
+]);
+function getTemplatesDir() {
+    return node_path_1.default.join((0, paths_1.getCliPackageRoot)(), 'templates');
+}
+function copyDirFiltered(srcDir, destDir, skipNames = THEME_COPY_SKIP) {
+    node_fs_1.default.mkdirSync(destDir, { recursive: true });
+    for (const entry of node_fs_1.default.readdirSync(srcDir, { withFileTypes: true })) {
+        if (skipNames.has(entry.name))
+            continue;
+        const from = node_path_1.default.join(srcDir, entry.name);
+        const to = node_path_1.default.join(destDir, entry.name);
+        if (entry.isDirectory()) {
+            copyDirFiltered(from, to, skipNames);
+        }
+        else if (entry.isFile()) {
+            node_fs_1.default.copyFileSync(from, to);
+        }
+    }
+}
+function resolveThemeTemplateDir() {
+    const bundled = node_path_1.default.join(getTemplatesDir(), 'site-theme');
+    if (node_fs_1.default.existsSync(node_path_1.default.join(bundled, 'theme.json'))) {
+        return bundled;
+    }
+    const monorepoTheme = node_path_1.default.join((0, paths_1.getCliPackageRoot)(), '..', 'themes', 'hello-world');
+    if (node_fs_1.default.existsSync(node_path_1.default.join(monorepoTheme, 'theme.json'))) {
+        return monorepoTheme;
+    }
+    return null;
+}
+function writeActiveThemeManifest(projectRoot) {
+    const manifestPath = node_path_1.default.join(projectRoot, ACTIVE_THEME_MANIFEST_REL);
+    node_fs_1.default.mkdirSync(node_path_1.default.dirname(manifestPath), { recursive: true });
+    node_fs_1.default.writeFileSync(manifestPath, JSON.stringify({
+        activeTheme: 'hello-world',
+        themeDir: THEME_RUNTIME_REL.replace(/\\/g, '/'),
+        updatedAt: new Date().toISOString(),
+    }, null, 2), 'utf8');
+}
+function seedBundledTheme(projectRoot) {
+    const themeTemplate = resolveThemeTemplateDir();
+    if (!themeTemplate) {
+        throw new Error((0, i18n_1.t)('createSite.themeTemplateMissing'));
+    }
+    const targetDir = node_path_1.default.join(projectRoot, THEME_RUNTIME_REL);
+    if (node_fs_1.default.existsSync(targetDir)) {
+        node_fs_1.default.rmSync(targetDir, { recursive: true, force: true });
+    }
+    copyDirFiltered(themeTemplate, targetDir);
+    const themePkgPath = node_path_1.default.join(targetDir, 'package.json');
+    if (node_fs_1.default.existsSync(themePkgPath)) {
+        const pkg = JSON.parse(node_fs_1.default.readFileSync(themePkgPath, 'utf8'));
+        pkg.dependencies = pkg.dependencies || {};
+        pkg.dependencies['@fecommunity/reactpress-toolkit'] =
+            pkg.dependencies['@fecommunity/reactpress-toolkit'] || `^${(0, paths_1.getCliVersion)()}`;
+        delete pkg.dependencies['@fecommunity/reactpress-web'];
+        node_fs_1.default.writeFileSync(themePkgPath, JSON.stringify(pkg, null, 2), 'utf8');
+    }
+    writeActiveThemeManifest(projectRoot);
+}
+function linkThemeNodeModules(projectRoot) {
+    const siteModules = node_path_1.default.join(projectRoot, 'node_modules');
+    const themeModules = node_path_1.default.join(projectRoot, THEME_RUNTIME_REL, 'node_modules');
+    if (!node_fs_1.default.existsSync(siteModules))
+        return;
+    if (node_fs_1.default.existsSync(themeModules)) {
+        try {
+            const stat = node_fs_1.default.lstatSync(themeModules);
+            if (stat.isSymbolicLink())
+                return;
+        }
+        catch {
+            // fall through
+        }
+        node_fs_1.default.rmSync(themeModules, { recursive: true, force: true });
+    }
+    node_fs_1.default.symlinkSync(node_path_1.default.relative(node_path_1.default.dirname(themeModules), siteModules), themeModules, 'dir');
+}
+function renderSitePackageJson(projectName) {
+    const templatePath = node_path_1.default.join(getTemplatesDir(), 'site', 'package.json');
+    const raw = node_fs_1.default.readFileSync(templatePath, 'utf8');
+    return raw
+        .replace(/\{\{name\}\}/g, projectName)
+        .replace(/\{\{reactpressVersion\}\}/g, `^${(0, paths_1.getCliVersion)()}`);
+}
+function copySiteScaffold(projectRoot, projectName) {
+    node_fs_1.default.mkdirSync(projectRoot, { recursive: true });
+    node_fs_1.default.writeFileSync(node_path_1.default.join(projectRoot, 'package.json'), renderSitePackageJson(projectName), 'utf8');
+    const gitignoreSrc = node_path_1.default.join(getTemplatesDir(), 'site', 'gitignore');
+    if (node_fs_1.default.existsSync(gitignoreSrc)) {
+        node_fs_1.default.copyFileSync(gitignoreSrc, node_path_1.default.join(projectRoot, '.gitignore'));
+    }
+}
+function getNpmCommand() {
+    return process.platform === 'win32' ? 'npm.cmd' : 'npm';
+}
+function installSiteDependencies(projectRoot, { quiet = false } = {}) {
+    console.log(`[reactpress] ${(0, i18n_1.t)('createSite.installingDeps')}`);
+    const result = (0, node_child_process_1.spawnSync)(getNpmCommand(), ['install', '--legacy-peer-deps', '--no-fund', '--no-audit'], {
+        cwd: projectRoot,
+        stdio: quiet ? 'pipe' : 'inherit',
+        shell: process.platform === 'win32',
+        env: {
+            ...process.env,
+            npm_config_ignore_scripts: 'true',
+        },
+    });
+    if (result.status !== 0) {
+        throw new Error((0, i18n_1.t)('createSite.installFailed'));
+    }
+}
+async function createSite(options) {
+    const projectRoot = node_path_1.default.resolve(options.directory);
+    const projectName = options.name ||
+        (node_path_1.default.basename(projectRoot) || 'reactpress-site').replace(/^@/, '').replace(/\//g, '-');
+    if (node_fs_1.default.existsSync(node_path_1.default.join(projectRoot, '.reactpress', 'config.json')) && !options.force) {
+        return {
+            ok: false,
+            projectRoot,
+            message: (0, i18n_1.t)('createSite.alreadyExists'),
+        };
+    }
+    console.log(`[reactpress] ${(0, i18n_1.t)('createSite.scaffolding', { dir: projectRoot })}`);
+    copySiteScaffold(projectRoot, projectName);
+    process.env.REACTPRESS_LOCAL_MODE = '1';
+    process.env.REACTPRESS_SKIP_NGINX = '1';
+    const initResult = await (0, local_site_1.initLocalProject)(projectRoot, { force: options.force });
+    if (!initResult.ok) {
+        return initResult;
+    }
+    seedBundledTheme(projectRoot);
+    if (!options.skipInstall) {
+        try {
+            installSiteDependencies(projectRoot);
+            linkThemeNodeModules(projectRoot);
+        }
+        catch (err) {
+            return {
+                ok: true,
+                projectRoot,
+                message: (0, i18n_1.t)('createSite.createdInstallSkipped', {
+                    error: err.message || String(err),
+                }),
+            };
+        }
+    }
+    console.log('');
+    console.log(`[reactpress] ${(0, i18n_1.t)('createSite.ready')}`);
+    console.log(`  cd ${projectRoot === process.cwd() ? '.' : projectRoot}`);
+    console.log(`  npm run dev`);
+    console.log('');
+    console.log((0, i18n_1.t)('createSite.urlsHint'));
+    return {
+        ok: true,
+        projectRoot,
+        message: (0, i18n_1.t)('createSite.done'),
+    };
+}
+module.exports = {
+    createSite,
+    seedBundledTheme,
+    linkThemeNodeModules,
+};
+//# sourceMappingURL=create-site.js.map

package/out/lib/database-mode.js

@@ -0,0 +1,45 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+// @ts-nocheck
+const fs = require('fs');
+const path = require('path');
+const { ensureOriginalCwd } = require('./root');
+function isDesktopLocalMode() {
+    return process.env.REACTPRESS_DESKTOP_LOCAL === '1';
+}
+function readSqliteModeFromProject(projectRoot) {
+    try {
+        const configPath = path.join(projectRoot, '.reactpress/config.json');
+        if (fs.existsSync(configPath)) {
+            const config = JSON.parse(fs.readFileSync(configPath, 'utf8'));
+            if (config.database?.mode === 'embedded-sqlite')
+                return true;
+        }
+    }
+    catch {
+        // ignore
+    }
+    try {
+        const envPath = path.join(projectRoot, '.env');
+        if (fs.existsSync(envPath)) {
+            const content = fs.readFileSync(envPath, 'utf8');
+            if (/^DB_TYPE=sqlite/m.test(content))
+                return true;
+        }
+    }
+    catch {
+        // ignore
+    }
+    return false;
+}
+function isLocalSqliteMode(projectRoot = ensureOriginalCwd()) {
+    if (process.env.REACTPRESS_LOCAL_MODE === '1' || isDesktopLocalMode())
+        return true;
+    return readSqliteModeFromProject(projectRoot);
+}
+module.exports = {
+    isDesktopLocalMode,
+    isLocalSqliteMode,
+    readSqliteModeFromProject,
+};
+//# sourceMappingURL=database-mode.js.map

package/out/lib/design-tokens.js

@@ -0,0 +1,55 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.REPO_DISPLAY = exports.REPO_URL = exports.TECH_LOGO = exports.logoGradients = exports.layout = exports.motion = exports.palette = void 0;
+/** Shared visual tokens for legacy chalk UI and Ink shell. */
+exports.palette = {
+    primary: '#7C5CFF',
+    accent: '#22D3EE',
+    pink: '#F472B6',
+    green: '#22C55E',
+    amber: '#F59E0B',
+    red: '#EF4444',
+    gray: '#6B7280',
+    dim: '#9CA3AF',
+    border: '#4A4580',
+    surface: '#12152A',
+    surfaceRaised: '#1A1F3A',
+    ink: '#0B1220',
+};
+exports.motion = {
+    bootLogoMs: 90,
+    bootMetaMs: 180,
+    pulsePeriodMs: 800,
+    shimmerMs: 1200,
+    statusPollMs: 2000,
+    transitionMs: 150,
+    maxFps: 15,
+};
+exports.layout = {
+    cardPadX: 2,
+    sectionGap: 1,
+    shellPadX: 1,
+    minContentWidth: 40,
+    maxContentWidth: 96,
+    stackBreakpoint: 68,
+};
+/** Per-line gradient pairs for the ASCII logo (from → to). */
+exports.logoGradients = [
+    [exports.palette.pink, exports.palette.primary],
+    [exports.palette.pink, exports.palette.primary],
+    [exports.palette.primary, exports.palette.accent],
+    [exports.palette.primary, exports.palette.accent],
+    [exports.palette.accent, exports.palette.primary],
+    [exports.palette.accent, exports.palette.primary],
+];
+exports.TECH_LOGO = [
+    '██████╗ ███████╗ █████╗  ██████╗████████╗██████╗ ██████╗ ███████╗███████╗███████╗',
+    '██╔══██╗██╔════╝██╔══██╗██╔════╝╚══██╔══╝██╔══██╗██╔══██╗██╔════╝██╔════╝██╔════╝',
+    '██████╔╝█████╗  ███████║██║        ██║   ██████╔╝██████╔╝█████╗  ███████╗███████╗',
+    '██╔══██╗██╔══╝  ██╔══██║██║        ██║   ██╔═══╝ ██╔══██╗██╔══╝  ╚════██║╚════██║',
+    '██║  ██║███████╗██║  ██║╚██████╗   ██║   ██║     ██║  ██║███████╗███████║███████║',
+    '╚═╝  ╚═╝╚══════╝╚═╝  ╚═╝ ╚═════╝   ╚═╝   ╚═╝     ╚═╝  ╚═╝╚══════╝╚══════╝╚══════╝',
+];
+exports.REPO_URL = 'https://github.com/fecommunity/reactpress';
+exports.REPO_DISPLAY = 'github.com/fecommunity/reactpress';
+//# sourceMappingURL=design-tokens.js.map

package/out/lib/dev-banner.js

@@ -6,12 +6,16 @@ const { loadClientSiteUrl, loadWebAdminUrl, loadServerSiteUrl, getApiPrefix, get
 const { hasWeb } = require('./project-type');
 const { nginxEntryUrl } = require('./nginx');
 const { t } = require('./i18n');
+function normalizeUrl(value, fallback) {
+    const raw = String(value || fallback || '').trim();
+    return raw.replace(/\/$/, '');
+}
 function getDevUrls(projectRoot) {
-    const client = loadClientSiteUrl(projectRoot).replace(/\/$/, '');
-    const server = loadServerSiteUrl(projectRoot).replace(/\/$/, '');
-    const prefix = getApiPrefix(projectRoot).replace(/\/$/, '') || '/api';
+    const client = normalizeUrl(loadClientSiteUrl(projectRoot), 'http://localhost:3001');
+    const server = normalizeUrl(loadServerSiteUrl(projectRoot), 'http://localhost:3002');
+    const prefix = normalizeUrl(getApiPrefix(projectRoot), '/api') || '/api';
     const admin = hasWeb(projectRoot)
-        ? loadWebAdminUrl(projectRoot).replace(/\/$/, '')
+        ? normalizeUrl(loadWebAdminUrl(projectRoot), 'http://localhost:3000')
         : `${client}/admin`;
     return {
         site: client,
@@ -52,7 +56,8 @@ function printDevReadyBanner(projectRoot, { apiOnly = false, webOnly = false, de
         if (hasThemeSite) {
             console.log(urlLine(t('devBanner.site'), urls.site));
         }
-        const healthUrl = localApiUrl.replace(/\/api\/?$/, '') + '/api/health';
+        const healthUrl = String(localApiUrl || '')
+            .replace(/\/api\/?$/, '') + '/api/health';
         console.log(urlLine(t('devBanner.health'), healthUrl, { underline: false }));
         console.log(`  ${brand.muted('  ')}${brand.dim(t(localWeb ? 'devBanner.localWebHint' : 'devBanner.desktopLocalHint'))}`);
     }

package/out/lib/dev-session.js

@@ -4,7 +4,8 @@ Object.defineProperty(exports, "__esModule", { value: true });
 const fs = require('fs');
 const path = require('path');
 function lockFilePath(projectRoot) {
-    return path.join(projectRoot, '.reactpress', 'dev-session.json');
+    const { devSessionSuffix } = require('./ports');
+    return path.join(projectRoot, '.reactpress', `dev-session${devSessionSuffix()}.json`);
 }
 function isPidAlive(pid) {
     const n = parseInt(pid, 10);
@@ -60,7 +61,13 @@ async function acquireDevSession(projectRoot) {
             // Do not run `docker compose down` here — DB/nginx containers must survive dev restarts.
         }
     }
-    const { releaseStaleDevStackPorts } = require('./ports');
+    const { releaseStaleDevStackPorts, resolveDevStackPorts, applyDevStackPortsToEnv, readInstanceIndex, } = require('./ports');
+    const stack = resolveDevStackPorts(resolvedRoot);
+    applyDevStackPortsToEnv(stack);
+    const instance = stack.admin !== 3000 || stack.api !== 3002 ? readInstanceIndex() : 0;
+    if (instance > 0) {
+        console.log(`[reactpress] Dev instance ${instance} — admin :${stack.admin}, api :${stack.api}, visitor :${stack.visitor}, preview :${stack.preview}`);
+    }
     await releaseStaleDevStackPorts(resolvedRoot);
     fs.mkdirSync(path.dirname(lockPath), { recursive: true });
     fs.writeFileSync(lockPath, `${JSON.stringify({

package/out/lib/dev.js

@@ -25,6 +25,7 @@ const { acquireDevSession, releaseDevSession } = require('./dev-session');
 const { checkNodeVersion, checkDocker } = require('./doctor');
 const { startDevTimer, markDevPhase, isDevVerbose, logDevLine, logDevDetail, logDevStatus, logDevTimingSummary, } = require('./dev-log');
 const { t } = require('./i18n');
+const { isDesktopLocalMode, isLocalSqliteMode } = require('./database-mode');
 const { resolveRemoteThemeApiBase, readDevClientApiOrigin, normalizeRemoteOrigin, } = require('./remote-dev');
 const CLIENT_READY_TIMEOUT_MS = 120_000;
 const API_READY_TIMEOUT_MS = 180_000;
@@ -39,11 +40,24 @@ function logDevPhase(step, total, messageKey, vars = {}) {
     console.log('');
     console.log(`[reactpress] [${step}/${total}] ${t(messageKey, vars)}`);
 }
-function isDesktopLocalMode() {
-    return process.env.REACTPRESS_DESKTOP_LOCAL === '1';
-}
-function isLocalSqliteMode() {
-    return process.env.REACTPRESS_LOCAL_MODE === '1' || isDesktopLocalMode();
+async function applyAutoLocalDevFallback(projectRoot, { needsLocalApi = true } = {}) {
+    if (!needsLocalApi)
+        return false;
+    if (isLocalSqliteMode(projectRoot)) {
+        process.env.REACTPRESS_SKIP_NGINX = '1';
+        return false;
+    }
+    if (process.env.REACTPRESS_FORCE_MYSQL === '1')
+        return false;
+    const docker = checkDocker();
+    const mysqlOk = docker.ok ? await probeMysqlHost(projectRoot) : false;
+    if (docker.ok && mysqlOk)
+        return false;
+    process.env.REACTPRESS_LOCAL_MODE = '1';
+    process.env.REACTPRESS_SKIP_NGINX = '1';
+    console.log('');
+    console.log(`[reactpress] ${t(docker.ok ? 'dev.autoLocalNoMysql' : 'dev.autoLocalNoDocker')}`);
+    return true;
 }
 function desktopPhaseKey(defaultKey) {
     if (isLocalSqliteMode()) {
@@ -263,7 +277,7 @@ async function spawnAdminWeb(projectRoot, { behindNginx = false, integratedStack
             adminEnv.VITE_DEV_API_PROXY_TARGET = normalizeRemoteOrigin(adminApiOrigin) || adminApiOrigin;
         }
         else if (isDesktopLocalMode() && process.env.REACTPRESS_DESKTOP_LOCAL_API) {
-            // Desktop dev embeds SQLite API on a dedicated port (default :13102), not :3002.
+            // Local SQLite API uses the same port as SERVER_PORT (default :3002).
             adminEnv.VITE_DEV_API_PROXY_TARGET = process.env.REACTPRESS_DESKTOP_LOCAL_API.replace(/\/api\/?$/, '');
         }
         else {
@@ -323,17 +337,22 @@ function assertDevPrerequisites() {
 }
 async function prepareDevInfrastructure(projectRoot, { needsLocalApi = true } = {}) {
     await acquireDevSession(projectRoot);
-    if (isLocalSqliteMode()) {
+    if (isLocalSqliteMode(projectRoot)) {
+        const { ensureLocalSite } = require('../core/services/local-site');
+        const { ensureSqliteDatabase } = require('../core/services/database/sqlite');
+        const { syncEnvFromConfig, loadConfig } = require('../core/services/config');
+        const { getMonorepoRoot } = require('./root');
+        const port = readEnvPort(projectRoot, 'SERVER_PORT', DEV_PORTS.API);
         if (process.env.REACTPRESS_LOCAL_MODE === '1') {
-            const { ensureLocalSite } = require('../core/services/local-site');
-            const { ensureSqliteDatabase } = require('../core/services/database/sqlite');
-            const { getMonorepoRoot } = require('./root');
-            const port = readEnvPort(projectRoot, 'SERVER_PORT', DEV_PORTS.API);
             ensureLocalSite(projectRoot, port, { monorepoRoot: getMonorepoRoot() });
-            const sqliteResult = await ensureSqliteDatabase(projectRoot);
-            if (!sqliteResult.ok) {
-                throw new Error(sqliteResult.message || 'SQLite 数据库未就绪');
-            }
+        }
+        else {
+            const config = await loadConfig(projectRoot);
+            await syncEnvFromConfig(projectRoot, config);
+        }
+        const sqliteResult = await ensureSqliteDatabase(projectRoot);
+        if (!sqliteResult.ok) {
+            throw new Error(sqliteResult.message || 'SQLite 数据库未就绪');
         }
         nginxEnabled = false;
         delete process.env.REACTPRESS_NGINX_ENTRY_URL;
@@ -380,7 +399,9 @@ async function startDevStack(projectRoot, { webOnly = false, themeOnly = false,
             process.exit(1);
         }
     }
-    else if (needsLocalApi && !isLocalSqliteMode() && !(await probeMysqlHost(projectRoot))) {
+    else if (needsLocalApi &&
+        !isLocalSqliteMode(projectRoot) &&
+        !(await probeMysqlHost(projectRoot))) {
         console.error(t('dev.dbEnsureFailed', {
             message: t('docker.devStartBlocked', {
                 port: readEnvPort(projectRoot, 'DB_PORT', DEV_PORTS.MYSQL),
@@ -542,7 +563,7 @@ async function startDevStack(projectRoot, { webOnly = false, themeOnly = false,
             themeWait.then((ready) => {
                 if (ready)
                     logDevDetail('dev.themeReadyQuiet', { url: loadClientSiteUrl(projectRoot) });
-            });
+            }).catch(() => { });
         }
     }
     if (readinessWaits.length > 1) {
@@ -568,12 +589,17 @@ async function startDevStack(projectRoot, { webOnly = false, themeOnly = false,
             }
         });
     }
-    const dbOk = isDesktopLocalMode()
-        ? true
-        : needsLocalApi
-            ? await probeMysqlHost(projectRoot)
-            : true;
-    if (needsLocalApi && !dbOk && !isDesktopLocalMode()) {
+    let dbOk = true;
+    if (needsLocalApi) {
+        if (isDesktopLocalMode() || isLocalSqliteMode(projectRoot)) {
+            const { probeSqliteDatabase } = require('../core/services/database/sqlite');
+            dbOk = (await probeSqliteDatabase(projectRoot)).ok;
+        }
+        else {
+            dbOk = await probeMysqlHost(projectRoot);
+        }
+    }
+    if (needsLocalApi && !dbOk && !isDesktopLocalMode() && !isLocalSqliteMode(projectRoot)) {
         console.warn(t('dev.mysqlUnreachable'));
     }
     if (includeThemeSite && process.env.REACTPRESS_SKIP_PREVIEW_BUILD !== '1' && !prewarmPreviewBuilds) {
@@ -590,7 +616,11 @@ async function startDevStack(projectRoot, { webOnly = false, themeOnly = false,
         adminApiOrigin,
         clientApiOrigin,
         localApiUrl: isDesktopLocalMode() ? process.env.REACTPRESS_DESKTOP_LOCAL_API || null : null,
-        dbType: isDesktopLocalMode() ? 'sqlite' : needsLocalApi ? 'mysql' : null,
+        dbType: isDesktopLocalMode() || isLocalSqliteMode(projectRoot)
+            ? 'sqlite'
+            : needsLocalApi
+                ? 'mysql'
+                : null,
     });
     logDevTimingSummary({
         apiReused: Boolean(apiSpawn?.reused),
@@ -609,6 +639,7 @@ async function runDevStartup(projectRoot, { webOnly = false, themeOnly = false,
         console.error(formatDevFailureHint());
         process.exit(1);
     }
+    await applyAutoLocalDevFallback(projectRoot, { needsLocalApi: apiOrigins.needsLocalApi });
     logDevPhase(1, 3, desktopPhaseKey('dev.phasePrerequisites'));
     assertDevPrerequisites();
     logDevPhase(2, 3, desktopPhaseKey('dev.phaseInfra'));
@@ -643,10 +674,21 @@ async function startDesktopLocalApi(projectRoot, { forceRestart = false } = {})
         console.error(`[reactpress] ${t('dev.desktopMissing')}`);
         process.exit(1);
     }
+    const { resolveDevStackPorts, applyDevStackPortsToEnv, resolveApiPortForBind, } = require('./ports');
+    let stack = resolveDevStackPorts(projectRoot);
+    applyDevStackPortsToEnv(stack);
     const boot = await loadDesktopBootstrap(projectRoot);
     console.log('');
     logDevStatus('dev.desktopLocalApiStarting');
-    const { siteRoot, localApiBase } = await boot.startDesktopLocalApi(projectRoot, { forceRestart });
+    const resolved = await resolveApiPortForBind(projectRoot, { preferred: stack.api });
+    if (resolved.shifted || resolved.port !== stack.api) {
+        stack = { ...stack, api: resolved.port };
+        applyDevStackPortsToEnv(stack);
+    }
+    const { siteRoot, localApiBase } = await boot.startDesktopLocalApi(projectRoot, {
+        forceRestart,
+        port: resolved.port,
+    });
     process.env.REACTPRESS_DESKTOP_LOCAL_API = localApiBase;
     process.env.REACTPRESS_DESKTOP_SITE_ROOT = siteRoot;
     process.env.REACTPRESS_THEME_API_URL = localApiBase;
@@ -906,6 +948,7 @@ module.exports = {
     runDevStartup,
     buildToolkit,
     assertDevPrerequisites,
+    applyAutoLocalDevFallback,
     prepareDevInfrastructure,
     startDevStack,
     detectProjectType,