Merge branch 'main' of https://github.com/decentraland/js-sdk-toolchain into chore/sync-main-to-authserver

Author: pravusjif

packages/@dcl/sdk-commands/src/commands/start/explorer-alpha.ts

@@ -72,6 +72,7 @@ async function runApp(
   const landscapeTerrainEnabled = !!args['--landscape-terrain-enabled']
   const openDeeplinkInNewInstance = !!args['-n']
   const multiInstance = !!args['--multi-instance']
+  const assetBundles = !!args['--asset-bundles']
   const mcp = !!args['--mcp']
   const mcpPort = args['--mcp-port']
 
@@ -105,6 +106,11 @@ async function runApp(
     if (multiInstance) {
       params.set('multi-instance', 'true')
     }
+    if (assetBundles) {
+      // The explorer owns asset-bundle conversion: local-ab makes it spawn its own
+      // JIT converter against this preview's content server. No sidecar runs here.
+      params.set('local-ab', 'true')
+    }
     if (mcp) {
       params.set('mcp', 'true')
     }

packages/@dcl/sdk-commands/src/commands/start/index.ts

@@ -70,6 +70,7 @@ export const args = declareArgs({
   '--bevy-web': Boolean,
   '--web': '--bevy-web',
   '--multi-instance': Boolean,
+  '--asset-bundles': Boolean,
   '--no-client': Boolean,
   '--mcp': Boolean,
   '--mcp-port': Number
@@ -100,6 +101,7 @@ export async function help(options: Options) {
       --web, --bevy-web                 Opens preview using the Bevy Web browser window.
       --mobile                          Show QR code for mobile preview on the same network.
       --multi-instance                  Allow running multiple Explorer instances simultaneously.
+      --asset-bundles                   Preview with optimized asset bundles (forwarded as local-ab=true in the deep link; the Desktop Explorer converts the scene's assets itself).
       --no-client                       Suppress every auto-launch (desktop Explorer deeplink, browser open, mobile QR). The file watcher still notifies a desktop Explorer if it connects on its own — useful when an external tool owns the Explorer process.
       --mcp                             Enable the MCP server in the Explorer (forwarded as a deep link parameter).
       --mcp-port                        Port for the MCP server in the Explorer (forwarded as a deep link parameter).

packages/@dcl/sdk-commands/src/logic/get-free-port.ts

@@ -9,7 +9,10 @@ function tryListen(port: number): Promise<number> {
     const server = net.createServer()
     server.unref()
     server.once('error', reject)
-    server.listen(port, () => {
+    // probe the same address the servers bind (HTTP_SERVER_HOST=0.0.0.0): a hostless
+    // listen binds the IPv6 wildcard, which on macOS coexists with an IPv4 listener
+    // and reports ports as free that the real server then fails to bind (EADDRINUSE)
+    server.listen(port, '0.0.0.0', () => {
       const address = server.address()
       server.close(() => resolve(typeof address === 'object' && address ? address.port : port))
     })

test/sdk-commands/commands/start/explorer-alpha.spec.ts

@@ -185,6 +185,48 @@ describe('explorer-alpha', () => {
     })
   })
 
+  describe('assetBundles parameter', () => {
+    it('should include local-ab parameter when --asset-bundles flag is provided', async () => {
+      const args: any = {
+        '--asset-bundles': true
+      }
+
+      await runExplorerAlpha(mockComponents, {
+        cwd: '/test',
+        realm: 'test-realm',
+        baseCoords: { x: 0, y: 0 },
+        isHub: false,
+        args
+      })
+
+      expect(mockExec).toHaveBeenCalledWith(
+        '/test',
+        'open',
+        expect.arrayContaining([expect.stringContaining('local-ab=true')]),
+        { silent: true }
+      )
+    })
+
+    it('should not include local-ab parameter when --asset-bundles flag is not provided', async () => {
+      const args: any = {}
+
+      await runExplorerAlpha(mockComponents, {
+        cwd: '/test',
+        realm: 'test-realm',
+        baseCoords: { x: 0, y: 0 },
+        isHub: false,
+        args
+      })
+
+      expect(mockExec).toHaveBeenCalledWith(
+        '/test',
+        'open',
+        expect.arrayContaining([expect.not.stringContaining('local-ab')]),
+        { silent: true }
+      )
+    })
+  })
+
   describe('mcp parameter', () => {
     it('should include mcp parameter when --mcp flag is provided', async () => {
       const args: any = {

test/sdk-commands/utils/get-free-port.spec.ts

@@ -20,6 +20,31 @@ describe('utils/get-free-port', () => {
     expect(result).toBeLessThan(65536)
   })
 
+  it('never returns a port that is taken on 0.0.0.0, the address the preview server binds', async () => {
+    // occupy the base port (8000) with an IPv4-only listener, like a leftover preview server;
+    // a hostless probe binds the IPv6 wildcard and, on macOS, misses this listener entirely
+    const blocker = net.createServer()
+    blocker.unref()
+    const blocked = await new Promise<boolean>((resolve) => {
+      blocker.once('error', () => resolve(false))
+      blocker.listen(8000, '0.0.0.0', () => resolve(true))
+    })
+    try {
+      const result = await getPort(NaN, 123)
+      if (blocked) expect(result).not.toBe(8000)
+      // the returned port must be bindable on 0.0.0.0, exactly like the real server binds it
+      const server = net.createServer()
+      server.unref()
+      await new Promise<void>((resolve, reject) => {
+        server.once('error', reject)
+        server.listen(result, '0.0.0.0', () => resolve())
+      })
+      await new Promise((resolve) => server.close(resolve))
+    } finally {
+      if (blocked) await new Promise((resolve) => blocker.close(resolve))
+    }
+  })
+
   it('should return the fail-over port when probing fails', async () => {
     jest.spyOn(net, 'createServer').mockImplementation(() => {
       throw new Error('probe failed')