fix(dev): resolve local stack ports before startup

scripts/dev-stack-port-utils.test.ts

@@ -0,0 +1,51 @@
+import {createServer} from 'node:net';
+import {describe, expect, it} from 'vitest';
+import {
+  findAvailablePort,
+  resolveDevStackPorts,
+} from './dev-stack-port-utils.mjs';
+
+function reservePort(port) {
+  return new Promise((resolve, reject) => {
+    const server = createServer();
+
+    server.once('error', reject);
+    server.listen(port, '127.0.0.1', () => {
+      server.off('error', reject);
+      resolve(server);
+    });
+  });
+}
+
+describe('dev stack port utils', () => {
+  it('使用端口可用性检查为被占用端口寻找后续可用端口', async () => {
+    const firstServer = await reservePort(0);
+    const firstPort = firstServer.address().port;
+    const secondServer = await reservePort(firstPort + 1);
+
+    try {
+      const availablePort = await findAvailablePort({
+        host: '127.0.0.1',
+        preferredPort: firstPort,
+      });
+
+      expect(availablePort).toBeGreaterThan(firstPort + 1);
+    } finally {
+      await Promise.all([
+        new Promise((resolve) => firstServer.close(resolve)),
+        new Promise((resolve) => secondServer.close(resolve)),
+      ]);
+    }
+  });
+
+  it('为 npm run dev 的所有后续流程解析互不冲突的端口', async () => {
+    const resolvedPorts = await resolveDevStackPorts({
+      spacetime: {host: '127.0.0.1', preferredPort: 0},
+      api: {host: '127.0.0.1', preferredPort: 0},
+      web: {host: '127.0.0.1', preferredPort: 0},
+      adminWeb: {host: '127.0.0.1', preferredPort: 0},
+    });
+
+    expect(new Set(Object.values(resolvedPorts)).size).toBe(4);
+  });
+});