feat: split local dev into explicit service controls

Author: PerishCode

AGENTS.md

@@ -24,8 +24,12 @@ All commands use pnpm. Target a single app with `pnpm --filter <package>`.
 
 ```bash
 pnpm install                          # Install
-pnpm dev                              # Local controller-first web stack (Controller + Web)
-pnpm dev:controller                   # Controller only
+pnpm dev start <service>              # Start one local-dev service: desktop|openclaw|controller|web
+pnpm dev stop <service>               # Stop one local-dev service
+pnpm dev restart <service>            # Restart one local-dev service
+pnpm dev status <service>             # Show status for one local-dev service
+pnpm dev logs <service>               # Show active-session log tail (max 200 lines) for one local-dev service
+pnpm dev:controller                   # Legacy controller-only direct dev entrypoint
 pnpm start                            # Build and launch the desktop local runtime stack
 pnpm stop                             # Stop the desktop local runtime stack
 pnpm restart                          # Restart the desktop local runtime stack
@@ -69,6 +73,9 @@ This repo is desktop-first. Prefer the controller-first path and remove or ignor
 ## Desktop local development
 
 - Use `pnpm install` first, then `pnpm start` / `pnpm stop` / `pnpm restart` / `pnpm status` as the standard local desktop workflow.
+- For script-managed local development, use explicit per-service commands only: `pnpm dev start <desktop|openclaw|controller|web>`, `pnpm dev stop <service>`, `pnpm dev restart <service>`, `pnpm dev status <service>`, and `pnpm dev logs <service>`.
+- `pnpm dev` has no implicit aggregate default and intentionally does not support `all`; start each service deliberately in dependency order when you want the full local stack: `openclaw` -> `controller` -> `web` -> `desktop`.
+- `pnpm dev logs <service>` is session-scoped, prints a fixed header, and tails at most the last 200 lines from the active service session.
 - `pnpm start` is the canonical local desktop entrypoint and now applies safe startup optimizations by default: it reuses existing build artifacts when present and reuses the prepared OpenClaw sidecar cache when its inputs have not changed.
 - Temporary escape hatches exist for debugging or suspicious cache behavior: `NEXU_DESKTOP_FORCE_FULL_START=1` disables the optimized start path, `NEXU_DESKTOP_DISABLE_BUILD_REUSE=1` disables build artifact reuse only, and `NEXU_DESKTOP_DISABLE_OPENCLAW_SIDECAR_CACHE=1` disables the OpenClaw sidecar cache only.
 - `pnpm reset-state` is the reset button for the optimized path too: it stops the desktop runtime and clears repo-local runtime state plus cached sidecars under `.tmp/sidecars/`.
@@ -263,6 +270,8 @@ This note should track:
 - OpenClaw managed skills dir (expected default): `~/.openclaw/skills/`
 - Slack smoke probe setup: install Chrome Canary, set `PROBE_SLACK_URL`, run `pnpm probe:slack prepare`, then manually log into Slack in Canary before `pnpm probe:slack run`
 - `openclaw-runtime` is installed implicitly by `pnpm install`; local development should normally not use a global `openclaw` CLI
+- Local service startup order for the script-managed dev path: `pnpm dev start openclaw` -> `pnpm dev start controller` -> `pnpm dev start web` -> `pnpm dev start desktop`
+- Local service shutdown order for the script-managed dev path: `pnpm dev stop desktop` -> `pnpm dev stop web` -> `pnpm dev stop controller` -> `pnpm dev stop openclaw`
 - Prefer `./openclaw-wrapper` over global `openclaw` in local development; it executes `openclaw-runtime/node_modules/openclaw/openclaw.mjs`
 - When OpenClaw is started manually, set `RUNTIME_MANAGE_OPENCLAW_PROCESS=false` for `@nexu/controller` to avoid launching a second OpenClaw process
 - If behavior differs, verify effective `OPENCLAW_STATE_DIR` / `OPENCLAW_CONFIG_PATH` used by the running controller process.

TASK.md

@@ -41,6 +41,34 @@
 - Updated `scripts/dev/src/index.ts` so `pnpm dev start|restart|stop|status|logs` now includes `openclaw`
 - Updated existing `scripts/dev` controller/web assembly to consume injected values from `scripts/dev/.env` instead of assuming only hard-coded defaults
 
+### `scripts/dev` now also owns desktop local-dev attach
+
+- Added `scripts/dev/src/services/desktop.ts`
+- Updated `scripts/dev/src/index.ts` so `pnpm dev start|restart|stop|status|logs` now includes `desktop`
+- `scripts/dev` now launches desktop through `apps/desktop/scripts/dev-cli.mjs` with:
+  - `NEXU_DESKTOP_RUNTIME_MODE=external`
+  - injected controller/web/openclaw URLs from `scripts/dev/.env`
+  - shared `NEXU_HOME` from the `scripts/dev` contract
+- Added desktop-specific `scripts/dev` state/log plumbing:
+  - `.tmp/dev/desktop.pid`
+  - desktop log access wired to `.tmp/logs/desktop-dev.log`
+- `scripts/dev` command routing no longer has implicit aggregate defaults for `start | status | stop | restart`
+  - these commands now require an explicit single-service target: `desktop | openclaw | controller | web`
+  - aggregate target `all` is rejected
+  - example: `pnpm dev start openclaw`, `pnpm dev status desktop`, `pnpm dev stop web`
+- `pnpm dev logs <service>` is now session-scoped and tail-oriented:
+  - logs are resolved from the active service session only
+  - output is capped to the last 200 lines by default
+  - the CLI prints a fixed header with the tail policy, session line count, and actual log file path before log content
+  - desktop logs are sliced from the current `launchId` inside the shared `desktop-dev.log` file instead of dumping the whole file
+- Root `AGENTS.md` and `scripts/dev/AGENTS.md` were updated to describe the explicit per-service local-dev workflow, the lack of an `all` target, and the new session-scoped logging contract
+- Cleaned obvious old script-managed dev wording in service errors so each service now points to the matching explicit stop command (`pnpm dev stop <service>`)
+- `apps/desktop/main/bootstrap.ts` now respects a pre-injected `NEXU_HOME` in local dev instead of always forcing the desktop-local fallback path
+- `apps/desktop/scripts/dev-cli.mjs` now treats external runtime attach as a first-class mode for local dev:
+  - skips killing controller/web/openclaw listener ports when desktop is only attaching
+  - derives runtime ports from injected env instead of fixed desktop defaults
+  - skips controller/web/openclaw sidecar builds when external attach only needs desktop artifacts
+
 ### Small controller-chain robustness fix
 
 - `apps/controller/src/runtime/openclaw-config-writer.ts` now derives a fallback state dir from `openclawConfigPath` when the full env shape is not present, which fixed the related config-writer regression in tests
@@ -52,23 +80,36 @@
 - `pnpm --filter @nexu/controller typecheck` passed
 - `pnpm --filter @nexu/controller build` passed
 - `pnpm --dir ./scripts/dev exec tsc --noEmit` passed
-- Root-entrypoint local-dev acceptance for the current three-service flow passed:
-  - `pnpm dev status`
-  - `pnpm dev start`
-  - `pnpm dev status`
+- Root-entrypoint local-dev acceptance for explicit per-service local-dev flow passed:
+  - `pnpm dev status all` rejects `all` as intended
+  - `pnpm dev start openclaw`
   - `pnpm dev logs openclaw`
+  - `pnpm dev start controller`
   - `pnpm dev logs controller`
-  - `pnpm dev restart`
-  - `pnpm dev stop`
-  - `pnpm dev status`
+  - `pnpm dev start web`
+  - `pnpm dev logs web`
+  - `pnpm dev start desktop`
+  - `pnpm dev logs desktop`
+  - `pnpm dev stop desktop`
+  - `pnpm dev stop web`
+  - `pnpm dev stop controller`
+  - `pnpm dev stop openclaw`
+- Follow-up doc / cleanup validation passed:
+  - `pnpm --dir ./scripts/dev exec tsc --noEmit`
+  - grep audit across `AGENTS.md`, `scripts/dev/AGENTS.md`, and `scripts/dev/src/` for stale implicit-aggregate command wording
 - Verified controller now boots in `external` OpenClaw mode and successfully reaches `openclaw_ws_connected` through the `scripts/dev`-managed OpenClaw process
+- `pnpm lint` still fails, but only on pre-existing repo-wide Biome formatting drift unrelated to this branch
+- `pnpm test` still fails, but the observed failures are pre-existing desktop cross-platform/path test issues unrelated to this branch
 
 ## Important Current Behavior
 
 - OpenClaw local dev is now expected to be orchestrated by `scripts/dev`, not by its own dedicated `.env`
 - `scripts/dev/.env` is intended to become the single dev-only source of truth for cross-service injected runtime values
 - Controller local dev is already consuming OpenClaw through that external contract when launched via `scripts/dev`
-- Desktop code is prepared for the same external-runtime shape, but desktop is not yet wired into `scripts/dev`
+- Desktop local dev is now started/stopped through `scripts/dev` in `external` mode and attaches to the `scripts/dev`-managed controller/web/openclaw stack
+- `pnpm dev start|status|stop|restart` now require an explicit single-service target; `all` is intentionally unsupported
+- `pnpm dev logs <service>` only works for the active session of that service and prints at most the last 200 lines, prefixed with a fixed metadata header
+- Desktop still writes to the shared `.tmp/logs/desktop-dev.log`, but `pnpm dev logs desktop` now slices output to the current `launchId` session before tailing
 
 ## Known Existing Issues
 
@@ -77,10 +118,10 @@
   - `tests/nexu-config-store.test.ts`
   - `tests/openclaw-sync.test.ts`
   - `tests/openclaw-runtime-plugin-writer.test.ts` (Windows symlink permission issue)
-- Desktop is not yet started/stopped through `scripts/dev`; only `openclaw + controller + web` are wired today
+- `pnpm test` still has additional pre-existing desktop failures on Windows path expectations / filesystem assumptions (launchd, plist, state migration, skill path, runtime manifest, skill DB migration)
 
 ## Suggested Next Steps
 
-1. Wire `desktop` into `scripts/dev` using the same `scripts/dev/.env` contract and `NEXU_DESKTOP_RUNTIME_MODE=external`
-2. Decide whether to expand `pnpm dev` into explicit single-service targeting like `pnpm dev start openclaw` / `pnpm dev stop controller`
+1. Decide whether any per-service dependency guardrails are needed when users start `controller` or `desktop` without their expected upstream services already running
+2. Decide whether `logs` should gain an opt-in `--full` / `--lines <n>` escape hatch later, or remain hard-capped at 200 lines
 3. Continue tightening the `scripts/dev/.env` contract so every external injection is documented, named consistently, and traced to a single owner

apps/desktop/main/bootstrap.ts

@@ -52,7 +52,9 @@ function configureLocalDevPaths(): void {
   const userDataPath = resolve(electronRoot, "user-data");
   const sessionDataPath = resolve(electronRoot, "session-data");
   const logsPath = resolve(userDataPath, "logs");
-  const nexuHomePath = getDesktopNexuHomeDir(userDataPath);
+  const nexuHomePath = process.env.NEXU_HOME
+    ? resolve(process.env.NEXU_HOME)
+    : getDesktopNexuHomeDir(userDataPath);
 
   mkdirSync(userDataPath, { recursive: true });
   mkdirSync(sessionDataPath, { recursive: true });

apps/desktop/scripts/dev-cli.mjs

@@ -17,7 +17,6 @@ const logFile = resolve(logDir, "desktop-dev.log");
 const timelineFile = resolve(logDir, "desktop-startup-timeline.log");
 const managerDir = resolve(runtimeRoot, "manager");
 const stateFile = resolve(managerDir, "state.json");
-const defaultPorts = [18789, 50800, 50810];
 const cliFlags = new Set(process.argv.slice(3));
 const sidecarRoot = resolve(rootDir, ".tmp", "sidecars");
 
@@ -118,6 +117,42 @@ function shouldReuseBuildArtifacts() {
   return !isEnvFlagEnabled("NEXU_DESKTOP_DISABLE_BUILD_REUSE");
 }
 
+function getRuntimeMode() {
+  const explicitMode = process.env.NEXU_DESKTOP_RUNTIME_MODE?.trim();
+  if (explicitMode === "external") {
+    return "external";
+  }
+
+  if (isEnvFlagEnabled("NEXU_DESKTOP_EXTERNAL_RUNTIME")) {
+    return "external";
+  }
+
+  return "internal";
+}
+
+function readPort(value, fallback) {
+  const parsed = Number.parseInt(value ?? "", 10);
+  return Number.isInteger(parsed) && parsed > 0 ? parsed : fallback;
+}
+
+function getRuntimePorts() {
+  const controllerPort = readPort(
+    process.env.NEXU_CONTROLLER_PORT ?? process.env.NEXU_API_PORT,
+    50800,
+  );
+  const webPort = readPort(process.env.NEXU_WEB_PORT, 50810);
+
+  let openclawPort = 18789;
+  try {
+    const url = new URL(
+      process.env.NEXU_OPENCLAW_BASE_URL ?? "http://127.0.0.1:18789",
+    );
+    openclawPort = readPort(url.port, 18789);
+  } catch {}
+
+  return [openclawPort, controllerPort, webPort];
+}
+
 function createLauncherEnv() {
   return {
     ...process.env,
@@ -287,19 +322,25 @@ async function removeState() {
 }
 
 function hasReusableArtifacts() {
-  const requiredPaths = [
-    resolve(rootDir, "packages/shared/dist/index.js"),
-    resolve(rootDir, "apps/controller/dist/index.js"),
-    resolve(rootDir, "apps/web/dist/index.html"),
-    resolve(appDir, "dist/index.html"),
-    resolve(appDir, "dist-electron/main/bootstrap.js"),
-    resolve(rootDir, ".tmp/sidecars/controller/dist/index.js"),
-    resolve(
-      rootDir,
-      ".tmp/sidecars/openclaw/node_modules/openclaw/openclaw.mjs",
-    ),
-    resolve(rootDir, ".tmp/sidecars/web/index.js"),
-  ];
+  const requiredPaths =
+    getRuntimeMode() === "external"
+      ? [
+          resolve(appDir, "dist/index.html"),
+          resolve(appDir, "dist-electron/main/bootstrap.js"),
+        ]
+      : [
+          resolve(rootDir, "packages/shared/dist/index.js"),
+          resolve(rootDir, "apps/controller/dist/index.js"),
+          resolve(rootDir, "apps/web/dist/index.html"),
+          resolve(appDir, "dist/index.html"),
+          resolve(appDir, "dist-electron/main/bootstrap.js"),
+          resolve(rootDir, ".tmp/sidecars/controller/dist/index.js"),
+          resolve(
+            rootDir,
+            ".tmp/sidecars/openclaw/node_modules/openclaw/openclaw.mjs",
+          ),
+          resolve(rootDir, ".tmp/sidecars/web/index.js"),
+        ];
 
   return requiredPaths.every((filePath) => existsSync(filePath));
 }
@@ -560,9 +601,11 @@ async function killResidualProcesses() {
       await killPid(state.electronPid);
     }
 
-    const portPids = listListeningPids(defaultPorts);
-    for (const pid of portPids) {
-      await killPid(pid);
+    if (getRuntimeMode() !== "external") {
+      const portPids = listListeningPids(getRuntimePorts());
+      for (const pid of portPids) {
+        await killPid(pid);
+      }
     }
 
     await removeState();
@@ -572,43 +615,48 @@ async function killResidualProcesses() {
 async function buildRuntime() {
   const launcherEnv = createLauncherEnv();
   const webBuildEnv = createWebBuildEnv();
+  const runtimeMode = getRuntimeMode();
 
   await runTimedPhase("build_runtime", async () => {
-    await log("building runtime artifacts");
-    await logTimeline("build_runtime shared build start");
-    await runLogged(
-      pnpmCommand,
-      ["--dir", rootDir, "--filter", "@nexu/shared", "build"],
-      { env: launcherEnv },
-    );
-    await logTimeline("build_runtime controller build start");
-    await runLogged(
-      pnpmCommand,
-      ["--dir", rootDir, "--filter", "@nexu/controller", "build"],
-      { env: launcherEnv },
-    );
-    await logTimeline("build_runtime web build start");
-    await runLogged(
-      pnpmCommand,
-      ["--dir", rootDir, "--filter", "@nexu/web", "build"],
-      { env: webBuildEnv },
-    );
-    await logTimeline("build_runtime controller sidecar start");
-    await runLogged(
-      pnpmCommand,
-      ["--dir", appDir, "prepare:controller-sidecar"],
-      { env: launcherEnv },
-    );
-    await logTimeline("build_runtime openclaw sidecar start");
-    await runLogged(
-      pnpmCommand,
-      ["--dir", appDir, "prepare:openclaw-sidecar"],
-      { env: launcherEnv },
-    );
-    await logTimeline("build_runtime web sidecar start");
-    await runLogged(pnpmCommand, ["--dir", appDir, "prepare:web-sidecar"], {
-      env: launcherEnv,
-    });
+    await log(`building runtime artifacts mode=${runtimeMode}`);
+
+    if (runtimeMode !== "external") {
+      await logTimeline("build_runtime shared build start");
+      await runLogged(
+        pnpmCommand,
+        ["--dir", rootDir, "--filter", "@nexu/shared", "build"],
+        { env: launcherEnv },
+      );
+      await logTimeline("build_runtime controller build start");
+      await runLogged(
+        pnpmCommand,
+        ["--dir", rootDir, "--filter", "@nexu/controller", "build"],
+        { env: launcherEnv },
+      );
+      await logTimeline("build_runtime web build start");
+      await runLogged(
+        pnpmCommand,
+        ["--dir", rootDir, "--filter", "@nexu/web", "build"],
+        { env: webBuildEnv },
+      );
+      await logTimeline("build_runtime controller sidecar start");
+      await runLogged(
+        pnpmCommand,
+        ["--dir", appDir, "prepare:controller-sidecar"],
+        { env: launcherEnv },
+      );
+      await logTimeline("build_runtime openclaw sidecar start");
+      await runLogged(
+        pnpmCommand,
+        ["--dir", appDir, "prepare:openclaw-sidecar"],
+        { env: launcherEnv },
+      );
+      await logTimeline("build_runtime web sidecar start");
+      await runLogged(pnpmCommand, ["--dir", appDir, "prepare:web-sidecar"], {
+        env: launcherEnv,
+      });
+    }
+
     await logTimeline("build_runtime desktop build start");
     await runLogged(pnpmCommand, ["--dir", appDir, "build"], {
       env: launcherEnv,
@@ -749,7 +797,7 @@ async function status() {
     console.log(`[${timestamp()}] desktop process is not running`);
   }
 
-  const portPids = listListeningPids(defaultPorts);
+  const portPids = listListeningPids(getRuntimePorts());
   if (portPids.length > 0) {
     console.log(`listening pids: ${portPids.join(", ")}`);
   }