fix(app-tools): harden the dev lock against cross-process races

Review follow-ups on the initial implementation:
- registry mutex now publishes a fully-populated candidate directory and
  atomically renames it into place, so there is no created-but-unwritten
  owner window; dead-owner takeover is an atomic rename to a tombstone
  named after the dead owner's token, so concurrent waiters cannot
  displace the next holder, and a live holder is never broken
- `--allow-multiple` is resolved once at the run entry (typed
  `RunOptions.allowMultiple` wins over argv) and handed to the guard
  through a run-scoped, appDirectory-keyed intent
- the ready lock records the real listen URLs via `getAddressUrls`
  (HTTPS / custom host / IPv6 consistent with the terminal output) and is
  never marked ready when `listen` reports an error
- add the missing changeset and multi-process mutex tests (crash between
  create and rename, concurrent takeover, live-holder wait, exclusive
  sections never overlapping across real processes)

Co-Authored-By: Riff

Author: keepview

.changeset/dev-server-lock.md

@@ -0,0 +1,5 @@
+---
+'@modern-js/app-tools': patch
+---
+
+feat: add a project operation lock: `dev`/`start` register a shared lock and `build`/`deploy` hold an exclusive lock, so a second `modern dev` (or a build during dev) fails fast with the running instance's URL, PID and kill command instead of silently switching ports or clobbering `dist`; opt in to multiple dev servers with `modern dev --allow-multiple`

packages/solutions/app-tools/src/commands/dev.ts

@@ -10,6 +10,7 @@ import {
   type Alias,
   DEFAULT_DEV_HOST,
   SERVER_DIR,
+  getAddressUrls,
   getMeta,
   logger,
 } from '@modern-js/utils';
@@ -100,6 +101,28 @@ export const dev = async (
 
   const host = normalizedConfig.dev?.host || DEFAULT_DEV_HOST;
 
+  // Same protocol/host derivation as `prettyInstructions`, so the URLs in
+  // the lock file match what the terminal prints (HTTPS, custom host, IPv6).
+  const markLockReady = () => {
+    const isHttps = Boolean(
+      normalizedConfig.dev?.https ||
+        (normalizedConfig.tools as { devServer?: { https?: unknown } })
+          ?.devServer?.https,
+    );
+    markDevLockReady(appDirectory, metaName, {
+      port,
+      host,
+      urls:
+        typeof port === 'number'
+          ? getAddressUrls(
+              isHttps ? 'https' : 'http',
+              port,
+              normalizedConfig.dev?.host,
+            ).map(({ url }) => url)
+          : undefined,
+    });
+  };
+
   if (apiOnly) {
     const { server } = await createDevServer(
       {
@@ -115,10 +138,7 @@ export const dev = async (
         host,
       },
       () => {
-        markDevLockReady(appContext.appDirectory, appContext.metaName, {
-          port,
-          host,
-        });
+        markLockReady();
         printInstructions(
           hooks,
           appContext,
@@ -144,14 +164,13 @@ export const dev = async (
       async (err?: Error) => {
         if (err) {
           logger.error('Occur error %s, when start dev server', err);
+          // Never mark the lock ready for a server that failed to listen.
+          return;
         }
 
         logger.debug('listen dev server done');
 
-        markDevLockReady(appContext.appDirectory, appContext.metaName, {
-          port,
-          host,
-        });
+        markLockReady();
 
         await afterListen();
       },

packages/solutions/app-tools/src/plugins/devLock.ts

@@ -2,6 +2,7 @@ import { getArgv, getCommand, minimist } from '@modern-js/utils';
 import type { AppTools, CliPlugin } from '../types';
 import {
   acquireCommandLock,
+  getDevLockIntent,
   normalizeLockOperation,
   releaseAllLocks,
   suspendForRestart,
@@ -30,17 +31,23 @@ export default (): CliPlugin<AppTools> => ({
         return;
       }
 
-      // The flag is consumed here, before Commander parses the command
-      // action options (which happens after `onPrepare`).
-      const args = minimist(getArgv(), {
-        boolean: ['allow-multiple'],
-      });
+      // The run entry (`createRunOptions`) parses `--allow-multiple` /
+      // `RunOptions.allowMultiple` and stores a run-scoped intent; raw argv
+      // is only a fallback for callers that drive `cli.init()` directly.
+      const intent = getDevLockIntent(appDirectory);
+      const allowMultiple =
+        intent?.allowMultiple ??
+        Boolean(
+          minimist(getArgv(), { boolean: ['allow-multiple'] })[
+            'allow-multiple'
+          ],
+        );
 
       await acquireCommandLock({
         appDirectory,
         metaName,
         operation,
-        allowMultiple: operation === 'dev' && Boolean(args['allow-multiple']),
+        allowMultiple: operation === 'dev' && allowMultiple,
       });
     });
 

packages/solutions/app-tools/src/run/index.ts

@@ -6,6 +6,7 @@ import { handleSetupResult } from '../compat/hooks';
 import {
   type DevServerLockError,
   isDevServerLockError,
+  setDevLockIntent,
 } from '../utils/devLock';
 import { getConfigFile } from '../utils/getConfigFile';
 import { loadInternalPlugins } from '../utils/loadPlugins';
@@ -18,6 +19,12 @@ export interface RunOptions {
   internalPlugins?: InternalPlugins;
   initialLog?: string;
   version: string;
+  /**
+   * Intentionally run this dev server alongside an already-running one
+   * (equivalent to the `--allow-multiple` CLI flag; the option wins over
+   * argv when both are present).
+   */
+  allowMultiple?: boolean;
 }
 export async function createRunOptions({
   cwd,
@@ -26,6 +33,7 @@ export async function createRunOptions({
   version,
   internalPlugins,
   configFile,
+  allowMultiple,
 }: RunOptions) {
   const nodeVersion = process.versions.node;
   const versionArr = nodeVersion.split('.').map(Number);
@@ -57,7 +65,8 @@ export async function createRunOptions({
   const cliParams = minimist<{
     c?: string;
     config?: string;
-  }>(process.argv.slice(2));
+    'allow-multiple'?: boolean;
+  }>(process.argv.slice(2), { boolean: ['allow-multiple'] });
   /**
    * Commands that support specify config files
    * `new` command need to use `--config-file` params,because `--config` is already used
@@ -88,6 +97,13 @@ export async function createRunOptions({
 
   const plugins = await loadInternalPlugins(appDirectory, internalPlugins);
 
+  // Single place where the multi-dev intent is resolved: the typed run
+  // option wins over the raw `--allow-multiple` flag. Stored run-scoped
+  // (keyed by appDirectory) for the dev-lock plugin to read in `onPrepare`.
+  setDevLockIntent(appDirectory, {
+    allowMultiple: allowMultiple ?? Boolean(cliParams['allow-multiple']),
+  });
+
   return {
     cwd,
     initialLog: initialLog || `Modern.js Framework v${version}`,