feat: add ngrok support for tunneling in DevCommand and update environment variables

Author: 3m1n3nc3

packages/common/package.json

@@ -63,5 +63,10 @@
         "arkormx": {
             "optional": true
         }
+    },
+    "inlinedDependencies": {
+        "clear-router": "2.9.3",
+        "dayjs": "1.11.20",
+        "kanun": "1.2.0"
     }
 }

packages/common/src/EnvLoader.ts

@@ -27,7 +27,14 @@ export class EnvLoader {
         this.loaded = true
 
         try {
-            loadEnvFile({ quiet: true })
+            loadEnvFile({
+                quiet: true,
+                // `ark dev` is a long-lived parent process. Its restarted server
+                // children inherit the parent's original dotenv values, so let
+                // each fresh child replace those cached values from the current
+                // file. Normal runtimes retain dotenv's shell-first precedence.
+                override: process.env.ARKSTACK_ENV_RELOAD === 'true',
+            })
         } catch {
             /** No .env file (or dotenv unavailable); use process.env as-is. */
         }
@@ -79,4 +86,4 @@ export class EnvLoader {
 /** 
  * Shared environment loader backing {@link env}.
  */
-export const envLoader = new EnvLoader()
+export const envLoader = new EnvLoader()

packages/common/src/types.ts

@@ -28,6 +28,7 @@ export interface EnvRegistry {
     APP_HOST: string
     APP_PORT: number
     APP_DEBUG: boolean
+    APP_SECURE: boolean
     APP_TIMEZONE: string
     APP_LOCALE: typeof locales[number]
     APP_FALLBACK_LOCALE: typeof locales[number]

packages/console/package.json

@@ -51,6 +51,7 @@
     "clear-router": "catalog:"
   },
   "dependencies": {
+    "@ngrok/ngrok": "^1.7.0",
     "@arkstack/common": "workspace:^",
     "@arkstack/contract": "workspace:^",
     "@h3ravel/musket": "catalog:",

packages/console/src/commands/DevCommand.ts

@@ -1,10 +1,12 @@
 import { dirname, join } from 'node:path'
 
 import { Arkstack } from '@arkstack/contract'
+import { env } from '@arkstack/common'
 import { Command } from '@h3ravel/musket'
 import { createRequire } from 'node:module'
 import { readFileSync } from 'node:fs'
 import { spawn } from 'node:child_process'
+import ngrok, { type Listener } from '@ngrok/ngrok'
 
 export interface DevServerOptions {
     /** 
@@ -35,6 +37,22 @@ export class DevCommand extends Command {
         const vars = DevCommand.devServerEnv(this.options())
         const rootDir = Arkstack.rootDir()
         const bin = DevCommand.resolveTsdownBin(rootDir)
+        let tunnel: Listener | undefined
+
+        if (this.option?.('tunnel')) {
+            tunnel = await ngrok.forward({
+                addr: Number(env('APP_PORT', env('PORT', 3000))),
+                authtoken: env('NGROK_AUTHTOKEN'),
+                domain: env('NGROK_DOMAIN'),
+            })
+
+            const url = tunnel.url()
+
+            if (url) {
+                vars.TUNNEL_URL = url
+                console.log(`Traffic has been tunnelled to ${url}`)
+            }
+        }
 
         // Run tsdown directly with node when we can resolve its bin — this avoids
         // the extra `pnpm exec` wrapper process. Fall back to `pnpm exec tsdown`
@@ -46,27 +64,31 @@ export class DevCommand extends Command {
                 ['exec', 'tsdown', '--log-level', 'silent'],
             ]
 
-        await new Promise<void>((resolve, reject) => {
-            const child = spawn(command, args, {
-                cwd: rootDir,
-                stdio: 'inherit',
-                env: Object.assign(process.env, vars),
-            })
-
-            child.on('error', (error) => {
-                reject(error)
-            })
-
-            child.on('exit', (code) => {
-                if (code === 0 || code === null) {
-                    resolve()
-
-                    return
-                }
-
-                reject(new Error(`tsdown exited with code ${code}`))
+        try {
+            await new Promise<void>((resolve, reject) => {
+                const child = spawn(command, args, {
+                    cwd: rootDir,
+                    stdio: 'inherit',
+                    env: Object.assign({}, process.env, vars),
+                })
+
+                child.on('error', (error) => {
+                    reject(error)
+                })
+
+                child.on('exit', (code) => {
+                    if (code === 0 || code === null) {
+                        resolve()
+
+                        return
+                    }
+
+                    reject(new Error(`tsdown exited with code ${code}`))
+                })
             })
-        })
+        } finally {
+            await tunnel?.close()
+        }
     }
 
     /**
@@ -97,7 +119,8 @@ export class DevCommand extends Command {
      *
      * The dev server binds `127.0.0.1` by default so it is local-only; `--host`
      * switches it to `0.0.0.0` to expose it on the local network. `--secure` flags
-     * the driver to serve HTTPS, and `--tunnel` enables the Ngrok tunnel.
+     * the driver to serve HTTPS. The command itself owns the Ngrok tunnel so
+     * watcher-driven application restarts cannot replace its public URL.
      * 
      * @param options 
      * @returns 
@@ -108,10 +131,7 @@ export class DevCommand extends Command {
         const vars: Record<string, string> = {
             NODE_ENV: 'development',
             APP_HOST: options.host ? '0.0.0.0' : '127.0.0.1',
-        }
-
-        if (options.tunnel) {
-            vars.TUNNEL = 'true'
+            ARKSTACK_ENV_RELOAD: 'true',
         }
 
         if (options.secure) {

packages/console/tests/dev-command.test.ts

@@ -9,6 +9,12 @@ vi.mock('node:child_process', () => {
     }
 })
 
+vi.mock('@ngrok/ngrok', () => ({
+    default: {
+        forward: vi.fn(),
+    },
+}))
+
 const makeChild = () => new EventEmitter() as EventEmitter & {
     on: (event: string, listener: (...args: any[]) => void) => EventEmitter;
 }
@@ -38,6 +44,7 @@ describe('DevCommand', () => {
                     ...process.env,
                     NODE_ENV: 'development',
                     APP_HOST: '127.0.0.1',
+                    ARKSTACK_ENV_RELOAD: 'true',
                 }
             },
         )
@@ -81,6 +88,39 @@ describe('DevCommand', () => {
         await expect(promise).rejects.toThrow('tsdown exited with code 1')
     })
 
+    it('keeps the tunnel in the dev command and passes its URL to the watcher', async () => {
+        const { spawn } = await import('node:child_process')
+        const { default: ngrok } = await import('@ngrok/ngrok')
+        const { DevCommand } = await import('../src/commands/DevCommand')
+        const close = vi.fn().mockResolvedValue(undefined)
+        const child = makeChild()
+
+        vi.mocked(ngrok.forward).mockResolvedValueOnce({
+            url: () => 'https://stable.ngrok.app',
+            close,
+        } as any)
+        vi.mocked(spawn).mockReturnValueOnce(child as any)
+
+        const promise = DevCommand.prototype.handle.call({
+            options: () => ({ tunnel: true }),
+            option: () => true,
+        })
+        await vi.waitFor(() => expect(spawn).toHaveBeenCalled())
+        child.emit('exit', 0)
+
+        await expect(promise).resolves.toBeUndefined()
+        expect(spawn).toHaveBeenLastCalledWith(
+            expect.any(String),
+            expect.any(Array),
+            expect.objectContaining({
+                env: expect.objectContaining({
+                    TUNNEL_URL: 'https://stable.ngrok.app',
+                }),
+            }),
+        )
+        expect(close).toHaveBeenCalledOnce()
+    })
+
     it('resolveTsdownBin resolves tsdown from the workspace', async () => {
         const { DevCommand } = await import('../src/commands/DevCommand')
 
@@ -97,6 +137,7 @@ describe('devServerEnv', () => {
 
         expect(vars.NODE_ENV).toBe('development')
         expect(vars.APP_HOST).toBe('127.0.0.1')
+        expect(vars.ARKSTACK_ENV_RELOAD).toBe('true')
         expect(vars.TUNNEL).toBeUndefined()
         expect(vars.APP_SECURE).toBeUndefined()
     })
@@ -107,11 +148,11 @@ describe('devServerEnv', () => {
         expect(DevCommand.devServerEnv({ host: true }).APP_HOST).toBe('0.0.0.0')
     })
 
-    it('--secure flags HTTPS and --tunnel enables Ngrok', async () => {
+    it('--secure flags HTTPS while the command manages Ngrok separately', async () => {
         const { DevCommand } = await import('../src/commands/DevCommand')
 
         expect(DevCommand.devServerEnv({ secure: true }).APP_SECURE).toBe('true')
-        expect(DevCommand.devServerEnv({ tunnel: true }).TUNNEL).toBe('true')
+        expect(DevCommand.devServerEnv({ tunnel: true }).TUNNEL).toBeUndefined()
     })
 
     it('combines all flags', async () => {
@@ -120,7 +161,7 @@ describe('devServerEnv', () => {
         expect(DevCommand.devServerEnv({ host: true, secure: true, tunnel: true })).toEqual({
             NODE_ENV: 'development',
             APP_HOST: '0.0.0.0',
-            TUNNEL: 'true',
+            ARKSTACK_ENV_RELOAD: 'true',
             APP_SECURE: 'true',
         })
     })

packages/driver-express/src/index.ts

@@ -143,12 +143,21 @@ export class ExpressDriver extends ArkstackKitDriver<Express, Handler> {
         const host = env('APP_HOST', env('HOST', '0.0.0.0'))
         const secure = env('APP_SECURE', false) === true
         const tunneled = env('TUNNEL', false)
+        const tunnelUrl = env('TUNNEL_URL')
         const scheme = secure ? 'https' : 'http'
 
         const onListen = async () => {
             let log = startupLogLines(scheme, host, port)
 
-            if (tunneled === true) {
+            if (tunnelUrl) {
+                log = log.concat(Logger.log([
+                    ['Traffic has been tunnelled to', 'white'],
+                    [tunnelUrl, 'green']
+                ], ' ', false))
+
+                this.tunnel_url = tunnelUrl
+                globalThis.tunnelUrl = () => tunnelUrl
+            } else if (tunneled === true) {
                 const listener = await ngrok.forward({
                     addr: port,
                     authtoken: env('NGROK_AUTHTOKEN'),
@@ -159,7 +168,7 @@ export class ExpressDriver extends ArkstackKitDriver<Express, Handler> {
 
                 if (url) {
                     log = log.concat(Logger.log([
-                        ['Trafic has been tunnelled to', 'white'],
+                        ['Traffic has been tunnelled to', 'white'],
                         [url, 'green']
                     ], ' ', false))
 

packages/driver-h3/src/index.ts

@@ -150,6 +150,7 @@ export class H3Driver extends ArkstackKitDriver<H3, H3Middleware> {
         const host = env('APP_HOST', env('HOST', '0.0.0.0'))
         const secure = env('APP_SECURE', false) === true
         const tunneled = env('TUNNEL', false)
+        const tunnelUrl = env('TUNNEL_URL')
         const scheme = secure ? 'https' : 'http'
 
         // Dev HTTPS: serve with an in-memory self-signed certificate.
@@ -164,7 +165,15 @@ export class H3Driver extends ArkstackKitDriver<H3, H3Middleware> {
 
         let log = startupLogLines(scheme, host, port)
 
-        if (tunneled === true) {
+        if (tunnelUrl) {
+            log = log.concat(Logger.log([
+                ['Traffic has been tunnelled to', 'white'],
+                [tunnelUrl, 'green']
+            ], ' ', false))
+
+            this.tunnel_url = tunnelUrl
+            globalThis.tunnelUrl = () => tunnelUrl
+        } else if (tunneled === true) {
             const listener = await ngrok.forward({
                 addr: port,
                 authtoken: env('NGROK_AUTHTOKEN'),
@@ -175,7 +184,7 @@ export class H3Driver extends ArkstackKitDriver<H3, H3Middleware> {
 
             if (url) {
                 log = log.concat(Logger.log([
-                    ['Trafic has been tunnelled to', 'white'],
+                    ['Traffic has been tunnelled to', 'white'],
                     [url, 'green']
                 ], ' ', false))