@fecommunity/reactpress 3.0.0 → 3.0.2

package/README.md

@@ -1,47 +1,93 @@
-# @fecommunity/reactpress-cli
+# @fecommunity/reactpress
 
-零配置一键初始化与管理 ReactPress CMS & 博客服务器。内置 NestJS 服务端，无需单独克隆 [fecommunity/reactpress](https://github.com/fecommunity/reactpress)。
+ReactPress 3.x 主包：一条命令完成站点初始化、本地开发、构建与生产部署。内置 NestJS API（站点项目无 `server/` 时自动使用 bundle），Monorepo 贡献者可使用仓库内 `server/` 源码联调。
 
-完整文档与贡献指南见：[github.com/fecommunity/reactpress-cli](https://github.com/fecommunity/reactpress-cli)
+[![npm version](https://img.shields.io/npm/v/@fecommunity/reactpress.svg)](https://www.npmjs.com/package/@fecommunity/reactpress)
+[![License: MIT](https://img.shields.io/npm/l/@fecommunity/reactpress.svg)](https://github.com/fecommunity/reactpress/blob/master/cli/LICENSE)
+
+完整文档：[github.com/fecommunity/reactpress](https://github.com/fecommunity/reactpress) · 中文说明见仓库 [README-zh_CN.md](https://github.com/fecommunity/reactpress/blob/master/README-zh_CN.md)
 
 ## 安装
 
 ```bash
-npm install -g @fecommunity/reactpress-cli
+npm install -g @fecommunity/reactpress@3
 ```
 
-全局命令为 `reactpress-cli`（与 npm 包名无关）。
+全局命令为 **`reactpress`**（推荐）。
 
-> npm 上的无作用域包名 `reactpress-cli` 已被占用，本包发布为 `@fecommunity/reactpress-cli`。
+> **兼容**：仍提供 `reactpress-cli` 别名，会映射到 `reactpress server *` 并打印弃用提示，**3.1 将移除**。旧包名 `@fecommunity/reactpress-cli` 请迁移到本包。
 
 ## 快速开始
 
+### 新建站点（零配置）
+
 ```bash
 mkdir my-blog && cd my-blog
-reactpress-cli init
-reactpress-cli start
+reactpress init
+reactpress dev
 ```
 
-浏览器访问 `http://localhost:3002`（API 文档：`/api`）。
+| 服务 | 默认地址 |
+|------|----------|
+| 前台 | http://localhost:3001 |
+| 后台 | http://localhost:3001/admin |
+| API / Swagger | http://localhost:3002/api |
+
+### 在本仓库（Monorepo）开发
+
+```bash
+git clone https://github.com/fecommunity/reactpress.git
+cd reactpress
+pnpm install
+pnpm init          # 生成 .env、.reactpress/config.json
+pnpm dev           # 等价于 reactpress dev
+```
 
 ## 常用命令
 
 | 命令 | 说明 |
 |------|------|
-| `reactpress-cli init [dir]` | 初始化项目 |
-| `reactpress-cli start` | 启动服务（自动准备数据库） |
-| `reactpress-cli stop` | 停止服务 |
-| `reactpress-cli restart` | 重启服务 |
-| `reactpress-cli status` | 查看状态 |
-| `reactpress-cli config [key] [value]` | 查看/修改配置 |
-| `reactpress-cli config server.port 3003 --apply` | 改端口并重启 |
+| `reactpress` | 交互式菜单 |
+| `reactpress init [dir]` | 初始化项目（`-f` 强制） |
+| `reactpress dev` | 环境检查 → 构建 toolkit → API + 前台 |
+| `reactpress dev --api-only` | 仅 API |
+| `reactpress dev --client-only` | 仅前台（需 API 已运行） |
+| `reactpress build -t <target>` | 构建：`toolkit` \| `server` \| `client` \| `docs` \| `all` |
+| `reactpress server start` | 后台启动 API（`--bg` 不等待健康检查） |
+| `reactpress server stop` / `restart` / `status` | API 生命周期 |
+| `reactpress start` | 生产：API + 前台 |
+| `reactpress status` | 统一状态（配置、端口、健康检查） |
+| `reactpress doctor` | 环境诊断 |
+| `reactpress docker up` / `down` / `start` / `status` / `logs` | Docker MySQL 与编排 |
+| `reactpress db backup` | 数据库备份（`mysqldump`） |
+| `reactpress publish` | Monorepo 发包向导（维护者） |
+
+站点级配置（`reactpress-cli` 时代）仍通过项目内 **`pnpm exec reactpress-cli config`** 或 `.reactpress/config.json` 管理；3.x 主路径为 `reactpress` + 根目录 `.env`。
+
+## 环境要求
+
+- **Node.js** ≥ 18
+- **pnpm** ≥ 8（Monorepo / `pnpm dev`）
+- **MySQL**：Docker（`reactpress docker up`）或 `.env` / `.reactpress/config.json` 中的外部库
+
+## 故障排查
+
+| 现象 | 处理 |
+|------|------|
+| `Missing script: build:toolkit` | 勿将 `REACTPRESS_ORIGINAL_CWD` 指到全局 npm 安装目录；在项目根执行，或 `unset REACTPRESS_ORIGINAL_CWD` 后重试 |
+| 误用 bundle API、未走 Monorepo `server/` | 确保在含 `pnpm-workspace.yaml` 的仓库根目录运行；升级至最新 `@fecommunity/reactpress` |
+| 端口占用 | `reactpress doctor` 或修改 `.env` 中 `SERVER_PORT` / `CLIENT_PORT` |
+
+## 相关包
 
-## 要求
+| 包 | 用途 |
+|----|------|
+| `@fecommunity/reactpress-client` | 仅部署 Next.js 前台 |
+| `@fecommunity/reactpress-toolkit` | OpenAPI 生成的 TS SDK |
+| `@fecommunity/reactpress-template-*` | 项目模板 |
 
-- Node.js 18+
-- macOS / Linux / Windows
-- 默认使用 Docker 运行嵌入式 MySQL；也可在 `.reactpress/config.json` 中配置外部数据库
+`@fecommunity/reactpress-server`、独立安装 `@fecommunity/reactpress-cli` 已弃用，请使用本包。
 
 ## 许可证
 
-MIT © FECommunity
+MIT © [FECommunity](https://github.com/fecommunity)

package/bin/reactpress.js

@@ -8,7 +8,8 @@
 const { Command } = require('commander');
 const path = require('path');
 const chalk = require('chalk');
-const { ensureOriginalCwd, getMonorepoRoot } = require('../lib/root');
+const { ensureOriginalCwd } = require('../lib/root');
+const { getCliPackageRoot } = require('../lib/paths');
 const { ensureProjectEnvironment, initMonorepoProject } = require('../lib/bootstrap');
 const { runDev } = require('../lib/dev');
 const { runApiDev } = require('../lib/api-dev');
@@ -24,7 +25,7 @@ const { getClientBin } = require('../lib/paths');
 const { runInteractiveLoop } = require('../ui/interactive');
 const { t } = require('../lib/i18n');
 
-const rootPkg = require(path.join(getMonorepoRoot(), 'package.json'));
+const rootPkg = require(path.join(getCliPackageRoot(), 'package.json'));
 
 const program = new Command();
 
@@ -62,7 +63,7 @@ program
     const projectRoot = ensureOriginalCwd();
     try {
       if (options.clientOnly) {
-        await runNodeScript(getClientBin(), [], { cwd: projectRoot });
+        await runNodeScript(getClientBin(projectRoot), [], { cwd: projectRoot });
         return;
       }
       if (options.apiOnly) {
@@ -121,13 +122,14 @@ clientCmd
   .option('--pm2', t('cli.client.start.pm2'))
   .action(async (options) => {
     const args = options.pm2 ? ['--pm2'] : [];
-    await runNodeScript(getClientBin(), args, { cwd: ensureOriginalCwd() });
+    const projectRoot = ensureOriginalCwd();
+    await runNodeScript(getClientBin(projectRoot), args, { cwd: projectRoot });
   });
 
 program
   .command('build')
   .description(t('cli.build.description'))
-  .option('-t, --target <target>', 'toolkit | server | client | docs | all', 'all')
+  .option('-t, --target <target>', t('cli.build.target'), 'all')
   .action(async (options) => {
     try {
       await runBuild(options.target, ensureOriginalCwd());
@@ -254,6 +256,7 @@ program.on('--help', () => {
   console.log(t('cli.help.status'));
   console.log(t('cli.help.doctor'));
   console.log(t('cli.help.docker'));
+  console.log(t('cli.help.build'));
   console.log(t('cli.help.publish'));
   console.log('');
 });

package/lib/api-dev.js

@@ -2,7 +2,7 @@ const { spawn, spawnSync } = require('child_process');
 const path = require('path');
 const { ensureProjectEnvironment } = require('./bootstrap');
 const { isUsingMonorepoServer } = require('./paths');
-const { getMonorepoRoot } = require('./root');
+const { ensureOriginalCwd } = require('./root');
 const { t } = require('./i18n');
 
 let apiChild;
@@ -11,7 +11,7 @@ function stopApiDev(projectRoot) {
   if (apiChild && !apiChild.killed) {
     apiChild.kill('SIGTERM');
   }
-  if (!isUsingMonorepoServer()) {
+  if (!isUsingMonorepoServer(projectRoot)) {
     spawnSync('pnpm', ['exec', 'reactpress-cli', 'stop'], {
       cwd: projectRoot,
       stdio: 'inherit',
@@ -20,7 +20,7 @@ function stopApiDev(projectRoot) {
 }
 
 function startApiDev(projectRoot) {
-  if (isUsingMonorepoServer()) {
+  if (isUsingMonorepoServer(projectRoot)) {
     console.log(t('apiDev.modeServer'));
     apiChild = spawn('pnpm', ['run', '--dir', './server', 'dev'], {
       cwd: projectRoot,
@@ -54,7 +54,7 @@ function startApiDev(projectRoot) {
   }
 }
 
-async function runApiDev(projectRoot = process.env.REACTPRESS_ORIGINAL_CWD || getMonorepoRoot()) {
+async function runApiDev(projectRoot = ensureOriginalCwd()) {
   try {
     await ensureProjectEnvironment(projectRoot);
   } catch (err) {

package/lib/bootstrap.js

@@ -1,7 +1,7 @@
 const fs = require('fs');
 const path = require('path');
 const { pathToFileURL } = require('url');
-const { getMonorepoRoot, isMonorepoCheckout } = require('./root');
+const { ensureOriginalCwd, isMonorepoCheckout } = require('./root');
 const { getCliPackageRoot } = require('./paths');
 const { t } = require('./i18n');
 
@@ -68,7 +68,7 @@ async function initMonorepoProject(projectRoot, { force = false } = {}) {
   };
 }
 
-async function ensureProjectEnvironment(projectRoot = getMonorepoRoot()) {
+async function ensureProjectEnvironment(projectRoot = ensureOriginalCwd()) {
   const root = path.resolve(projectRoot);
   const { setProjectCwd } = await importCliModule('utils/cli-context.js');
   setProjectCwd(root);

package/lib/build.js

@@ -1,29 +1,146 @@
+const fs = require('fs');
+const path = require('path');
+const chalk = require('chalk');
 const { runSync } = require('./spawn');
 const { ensureOriginalCwd } = require('./root');
 const { t } = require('./i18n');
 
-const TARGETS = {
-  toolkit: ['build:toolkit'],
-  server: ['build:server'],
-  client: ['build:client'],
-  docs: ['build:docs'],
-  all: ['build'],
+const FORBIDDEN_SCRIPTS = new Set(['build']);
+
+/** @type {Record<string, { script: string, labelKey: string }[]>} */
+const BUILD_STEPS = {
+  toolkit: [{ script: 'build:toolkit', labelKey: 'build.label.toolkit' }],
+  server: [{ script: 'build:server', labelKey: 'build.label.server' }],
+  client: [{ script: 'build:client', labelKey: 'build.label.client' }],
+  docs: [{ script: 'build:docs', labelKey: 'build.label.docs' }],
+  all: [
+    { script: 'build:toolkit', labelKey: 'build.label.toolkit' },
+    { script: 'build:server', labelKey: 'build.label.server' },
+    { script: 'build:client', labelKey: 'build.label.client' },
+  ],
 };
 
+const TARGETS = Object.keys(BUILD_STEPS);
+
+const buildChildEnv = { REACTPRESS_BUILD_ACTIVE: '1' };
+
+function readPackageScripts(packageJsonPath) {
+  try {
+    const pkg = JSON.parse(fs.readFileSync(packageJsonPath, 'utf8'));
+    return pkg.scripts || {};
+  } catch {
+    return {};
+  }
+}
+
+/** Prefer workspace package scripts over root package.json aliases. */
+function resolveBuildInvocation(script, projectRoot) {
+  const root = path.resolve(projectRoot);
+
+  if (script === 'build:toolkit') {
+    const toolkitDir = path.join(root, 'toolkit');
+    if (fs.existsSync(path.join(toolkitDir, 'package.json'))) {
+      return { command: 'pnpm', args: ['run', 'build'], cwd: toolkitDir };
+    }
+    const rootScripts = readPackageScripts(path.join(root, 'package.json'));
+    if (rootScripts['build:toolkit']) {
+      return { command: 'pnpm', args: ['run', 'build:toolkit'], cwd: root };
+    }
+    return null;
+  }
+
+  if (script === 'build:server') {
+    const serverDir = path.join(root, 'server');
+    if (fs.existsSync(path.join(serverDir, 'package.json'))) {
+      return { command: 'pnpm', args: ['run', 'build'], cwd: serverDir };
+    }
+  }
+
+  if (script === 'build:client') {
+    const clientDir = path.join(root, 'client');
+    if (fs.existsSync(path.join(clientDir, 'package.json'))) {
+      return { command: 'pnpm', args: ['run', 'build'], cwd: clientDir };
+    }
+  }
+
+  if (script === 'build:docs') {
+    const docsDir = path.join(root, 'docs');
+    if (fs.existsSync(path.join(docsDir, 'package.json'))) {
+      return { command: 'pnpm', args: ['run', 'build'], cwd: docsDir };
+    }
+  }
+
+  const rootScripts = readPackageScripts(path.join(root, 'package.json'));
+  if (rootScripts[script]) {
+    return { command: 'pnpm', args: ['run', script], cwd: root };
+  }
+
+  return null;
+}
+
 async function runBuild(target = 'all', projectRoot = ensureOriginalCwd()) {
-  const script = TARGETS[target];
-  if (!script) {
+  if (process.env.REACTPRESS_BUILD_ACTIVE === '1') {
+    throw new Error(t('build.recursive'));
+  }
+
+  const steps = BUILD_STEPS[target];
+  if (!steps) {
     throw new Error(
       t('build.unknownTarget', {
         target,
-        available: Object.keys(TARGETS).join(', '),
+        available: TARGETS.join(', '),
       })
     );
   }
-  for (const name of script) {
-    console.log(t('build.running', { name }));
-    runSync('pnpm', ['run', name], { cwd: projectRoot });
+
+  const total = steps.length;
+  const buildStarted = Date.now();
+
+  if (total > 1) {
+    console.log(t('build.plan', { total }));
+  }
+
+  for (let i = 0; i < steps.length; i++) {
+    const { script, labelKey } = steps[i];
+    if (FORBIDDEN_SCRIPTS.has(script)) {
+      throw new Error(t('build.forbiddenScript', { script }));
+    }
+
+    const current = i + 1;
+    const label = t(labelKey);
+    const stepStarted = Date.now();
+
+    console.log(t('build.step', { current, total, label }));
+
+    const invocation = resolveBuildInvocation(script, projectRoot);
+    if (!invocation) {
+      console.log(chalk.yellow(t('build.stepSkipped', { label })));
+      continue;
+    }
+
+    try {
+      runSync(invocation.command, invocation.args, {
+        cwd: invocation.cwd,
+        env: buildChildEnv,
+      });
+    } catch (err) {
+      console.error(chalk.red(t('build.stepFailed', { current, total, label })));
+      throw err;
+    }
+
+    const seconds = ((Date.now() - stepStarted) / 1000).toFixed(1);
+    console.log(chalk.green(t('build.stepDone', { current, total, label, seconds })));
+  }
+
+  if (total > 1) {
+    const totalSeconds = ((Date.now() - buildStarted) / 1000).toFixed(1);
+    console.log(chalk.green(t('build.done', { seconds: totalSeconds })));
   }
 }
 
-module.exports = { runBuild, TARGETS };
+module.exports = {
+  runBuild,
+  TARGETS,
+  BUILD_STEPS,
+  resolveBuildInvocation,
+};

package/lib/dev.js

@@ -1,5 +1,6 @@
 const { spawn } = require('child_process');
 const path = require('path');
+const { runBuild } = require('./build');
 const { ensureProjectEnvironment } = require('./bootstrap');
 const { loadServerSiteUrl, loadClientSiteUrl, waitForHttp } = require('./http');
 const { printDevReadyBanner } = require('./dev-banner');
@@ -30,20 +31,7 @@ function shutdown(signal = 'SIGINT') {
 }
 
 async function buildToolkit(projectRoot) {
-  return new Promise((resolve, reject) => {
-    const build = spawn('pnpm', ['build:toolkit'], {
-      stdio: 'inherit',
-      shell: true,
-      cwd: projectRoot,
-    });
-    build.on('close', (code) => {
-      if (code !== 0) {
-        reject(new Error(t('dev.toolkitFailed', { code })));
-        return;
-      }
-      resolve();
-    });
-  });
+  await runBuild('toolkit', projectRoot);
 }
 
 async function startDevStack(projectRoot) {

package/lib/i18n/strings.js

@@ -43,7 +43,9 @@ const STRINGS = {
     'cli.help.status': '  reactpress status           Combined status',
     'cli.help.doctor': '  reactpress doctor           Environment diagnostics',
     'cli.help.docker': '  reactpress docker start     Docker + full stack',
+    'cli.help.build': '  reactpress build -t client  Build one target (toolkit|server|client|docs|all)',
     'cli.help.publish': '  reactpress publish          Publish npm packages',
+    'cli.build.target': 'Build target: toolkit | server | client | docs | all',
     'banner.subtitle': '  ·  Full-stack publishing CLI        ',
     'menu.dev': 'Zero-config dev (env + DB + API + frontend)',
     'menu.init': 'Initialize project (.reactpress + .env + database)',
@@ -55,6 +57,8 @@ const STRINGS = {
     'menu.serverStop': 'Stop API',
     'menu.serverRestart': 'Restart API',
     'menu.build': 'Build (toolkit → server → client)',
+    'menu.buildTarget': 'What do you want to build?',
+    'menu.buildAll': 'All (toolkit → server → client)',
     'menu.dockerStart': 'Docker dev (DB + nginx + full stack)',
     'menu.dockerUp': 'Docker: database only',
     'menu.dockerStop': 'Stop Docker services',
@@ -193,7 +197,18 @@ const STRINGS = {
     'apiDev.ctrlCHint': '[reactpress] Press Ctrl+C to stop API.',
     'apiDev.stopHint': '[reactpress] Stop separately: reactpress server stop',
     'build.unknownTarget': 'Unknown build target: {target}. Available: {available}',
-    'build.running': '[reactpress] Building: {name}',
+    'build.recursive': 'Build recursion detected (pnpm run build must not call itself). Use build:toolkit, build:server, or build:client.',
+    'build.forbiddenScript': 'Invalid build script "{script}"; use granular scripts like build:toolkit.',
+    'build.stepFailed': '[reactpress] [{current}/{total}] {label} failed',
+    'build.plan': '[reactpress] Production build — {total} step(s): toolkit → server → client',
+    'build.step': '[reactpress] [{current}/{total}] {label}…',
+    'build.stepDone': '[reactpress] [{current}/{total}] {label} ✓ ({seconds}s)',
+    'build.stepSkipped': '[reactpress] Skipped {label} (not part of this project layout)',
+    'build.done': '[reactpress] Build finished in {seconds}s',
+    'build.label.toolkit': 'Toolkit',
+    'build.label.server': 'API (server)',
+    'build.label.client': 'Frontend (client)',
+    'build.label.docs': 'Documentation (docs)',
     'pm2.startFailed': '[reactpress] PM2 failed to start API:',
     'pm2.exitCode': 'PM2 exited with code {code}',
     'spawn.commandFailed': 'Command failed ({command}): exit code {code}',
@@ -320,7 +335,9 @@ const STRINGS = {
     'cli.help.status': '  reactpress status           综合状态',
     'cli.help.doctor': '  reactpress doctor           环境诊断',
     'cli.help.docker': '  reactpress docker start     Docker + 全栈',
+    'cli.help.build': '  reactpress build -t client  构建指定目标 (toolkit|server|client|docs|all)',
     'cli.help.publish': '  reactpress publish          发布 npm 包',
+    'cli.build.target': '构建目标: toolkit | server | client | docs | all',
     'banner.subtitle': '  ·  全栈发布平台 CLI        ',
     'menu.dev': '零配置开发 (env + DB + API + 前端)',
     'menu.init': '初始化项目 (.reactpress + .env + 数据库)',
@@ -332,6 +349,8 @@ const STRINGS = {
     'menu.serverStop': '停止 API',
     'menu.serverRestart': '重启 API',
     'menu.build': '构建 (toolkit → server → client)',
+    'menu.buildTarget': '选择要构建的目标',
+    'menu.buildAll': '全部 (toolkit → server → client)',
     'menu.dockerStart': 'Docker 开发环境 (DB + nginx + 全栈)',
     'menu.dockerUp': 'Docker 仅启动数据库',
     'menu.dockerStop': '停止 Docker 服务',
@@ -470,7 +489,18 @@ const STRINGS = {
     'apiDev.ctrlCHint': '[reactpress] 按 Ctrl+C 停止 API。',
     'apiDev.stopHint': '[reactpress] 单独停止: reactpress server stop',
     'build.unknownTarget': '未知构建目标: {target}，可选: {available}',
-    'build.running': '[reactpress] 构建: {name}',
+    'build.recursive': '检测到构建递归（pnpm run build 不能再次调用自身）。请使用 build:toolkit、build:server 或 build:client。',
+    'build.forbiddenScript': '无效的构建脚本 "{script}"，请使用 build:toolkit 等细分脚本。',
+    'build.stepFailed': '[reactpress] [{current}/{total}] {label} 失败',
+    'build.plan': '[reactpress] 生产构建 — 共 {total} 步：toolkit → server → client',
+    'build.step': '[reactpress] [{current}/{total}] {label}…',
+    'build.stepDone': '[reactpress] [{current}/{total}] {label} ✓ ({seconds}s)',
+    'build.stepSkipped': '[reactpress] 已跳过 {label}（当前项目无对应源码包）',
+    'build.done': '[reactpress] 构建完成，耗时 {seconds}s',
+    'build.label.toolkit': 'Toolkit',
+    'build.label.server': 'API (server)',
+    'build.label.client': '前端 (client)',
+    'build.label.docs': '文档 (docs)',
     'pm2.startFailed': '[reactpress] PM2 启动 API 失败:',
     'pm2.exitCode': 'PM2 退出码 {code}',
     'spawn.commandFailed': '命令失败 ({command}): 退出码 {code}',

package/lib/lifecycle.js

@@ -8,7 +8,7 @@ const {
   getPidFile,
 } = require('./paths');
 const { readPid, isProcessRunning, clearPidFile, writePid } = require('./process');
-const { getMonorepoRoot } = require('./root');
+const { ensureOriginalCwd } = require('./root');
 const { t } = require('./i18n');
 
 async function ensureConfig(projectRoot) {
@@ -46,7 +46,7 @@ async function startApi(projectRoot, { wait = true } = {}) {
   }
   clearPidFile(projectRoot);
 
-  if (!isUsingMonorepoServer()) {
+  if (!isUsingMonorepoServer(projectRoot)) {
     console.warn(t('lifecycle.noServerSrc'));
     const start = spawnSync('pnpm', ['exec', 'reactpress-cli', 'start'], {
       cwd: projectRoot,
@@ -56,8 +56,8 @@ async function startApi(projectRoot, { wait = true } = {}) {
   }
 
   console.log(t('lifecycle.startingLocalApi'));
-  const child = spawn(process.execPath, [getServerBin()], {
-    cwd: getServerDir(),
+  const child = spawn(process.execPath, [getServerBin(projectRoot)], {
+    cwd: getServerDir(projectRoot),
     detached: true,
     stdio: 'ignore',
     env: {
@@ -90,7 +90,7 @@ async function statusApi(projectRoot) {
   const { isHttpResponding } = require('./http');
   const httpOk = await isHttpResponding(serverUrl);
 
-  const source = isUsingMonorepoServer()
+  const source = isUsingMonorepoServer(projectRoot)
     ? t('lifecycle.source.monorepo')
     : t('lifecycle.source.bundle');
 
@@ -119,7 +119,7 @@ async function statusApi(projectRoot) {
   );
 }
 
-async function runLifecycleCommand(command, projectRoot = process.env.REACTPRESS_ORIGINAL_CWD || getMonorepoRoot()) {
+async function runLifecycleCommand(command, projectRoot = ensureOriginalCwd()) {
   switch (command) {
     case 'start':
       return startApi(projectRoot, { wait: true });
@@ -127,7 +127,7 @@ async function runLifecycleCommand(command, projectRoot = process.env.REACTPRESS
       return startApi(projectRoot, { wait: false });
     case 'stop':
       stopApi(projectRoot);
-      if (!isUsingMonorepoServer()) {
+      if (!isUsingMonorepoServer(projectRoot)) {
         spawnSync('pnpm', ['exec', 'reactpress-cli', 'stop'], {
           cwd: projectRoot,
           stdio: 'inherit',
@@ -136,7 +136,7 @@ async function runLifecycleCommand(command, projectRoot = process.env.REACTPRESS
       return 0;
     case 'restart':
       stopApi(projectRoot);
-      if (!isUsingMonorepoServer()) {
+      if (!isUsingMonorepoServer(projectRoot)) {
         spawnSync('pnpm', ['exec', 'reactpress-cli', 'restart'], {
           cwd: projectRoot,
           stdio: 'inherit',

package/lib/paths.js

@@ -1,13 +1,19 @@
 const fs = require('fs');
 const path = require('path');
-const { getMonorepoRoot } = require('./root');
+const { ensureOriginalCwd, getMonorepoRoot } = require('./root');
 
-function getMonorepoServerDir() {
-  return path.join(getMonorepoRoot(), 'server');
+function resolveProjectRoot(projectRoot) {
+  return path.resolve(projectRoot || ensureOriginalCwd());
 }
 
-function hasMonorepoServerSource() {
-  return fs.existsSync(path.join(getMonorepoServerDir(), 'src', 'main.ts'));
+function getMonorepoServerDir(projectRoot) {
+  return path.join(resolveProjectRoot(projectRoot), 'server');
+}
+
+function hasMonorepoServerSource(projectRoot) {
+  return fs.existsSync(
+    path.join(getMonorepoServerDir(projectRoot), 'src', 'main.ts')
+  );
 }
 
 function getCliPackageRoot() {
@@ -28,39 +34,53 @@ function getBundledServerDir() {
   return path.join(getCliPackageRoot(), 'server');
 }
 
-function getServerDir() {
-  if (hasMonorepoServerSource()) {
-    return getMonorepoServerDir();
+function getServerDir(projectRoot) {
+  if (hasMonorepoServerSource(projectRoot)) {
+    return getMonorepoServerDir(projectRoot);
   }
   return getBundledServerDir();
 }
 
-function getServerBin() {
-  return path.join(getServerDir(), 'bin', 'reactpress-server.js');
+function getServerBin(projectRoot) {
+  return path.join(getServerDir(projectRoot), 'bin', 'reactpress-server.js');
 }
 
-function getSwaggerPath() {
-  return path.join(getServerDir(), 'public', 'swagger.json');
+function getSwaggerPath(projectRoot) {
+  return path.join(getServerDir(projectRoot), 'public', 'swagger.json');
 }
 
-function getServerMain() {
-  return path.join(getServerDir(), 'dist', 'main.js');
+function getServerMain(projectRoot) {
+  return path.join(getServerDir(projectRoot), 'dist', 'main.js');
 }
 
-function isUsingMonorepoServer() {
-  return hasMonorepoServerSource();
+function isUsingMonorepoServer(projectRoot) {
+  return hasMonorepoServerSource(projectRoot);
 }
 
-function getClientBin() {
-  return path.join(getMonorepoRoot(), 'client', 'bin', 'reactpress-client.js');
+function getClientBin(projectRoot) {
+  const binPath = path.join(
+    resolveProjectRoot(projectRoot),
+    'client',
+    'bin',
+    'reactpress-client.js'
+  );
+  if (!fs.existsSync(binPath)) {
+    const err = new Error(
+      `Client entry not found: ${binPath}. Run from a ReactPress monorepo root or use reactpress-cli for site-only projects.`
+    );
+    err.code = 'REACTPRESS_CLIENT_NOT_FOUND';
+    throw err;
+  }
+  return binPath;
 }
 
 function getPidFile(projectRoot) {
-  return path.join(projectRoot, '.reactpress', 'server.pid');
+  return path.join(resolveProjectRoot(projectRoot), '.reactpress', 'server.pid');
 }
 
 module.exports = {
   getMonorepoRoot,
+  resolveProjectRoot,
   getMonorepoServerDir,
   hasMonorepoServerSource,
   isUsingMonorepoServer,

package/lib/pm2.js

@@ -5,9 +5,9 @@ const { t } = require('./i18n');
 
 function startApiWithPm2(projectRoot = ensureOriginalCwd()) {
   return new Promise((resolve, reject) => {
-    const child = spawn(process.execPath, [getServerBin(), '--pm2'], {
+    const child = spawn(process.execPath, [getServerBin(projectRoot), '--pm2'], {
       stdio: 'inherit',
-      cwd: getServerDir(),
+      cwd: getServerDir(projectRoot),
       env: {
         ...process.env,
         REACTPRESS_ORIGINAL_CWD: projectRoot,