refactor(devframe)!: split auth and rename internal under devframe/node (#332)

antfu · web-flow · commit f2068d81ae87 · 2026-05-11T14:13:27.000+09:00
BREAKING CHANGE: auth helpers (`getTempAuthToken`, `refreshTempAuthToken`,
`consumeTempAuthToken`, `getPendingAuth`, `setPendingAuth`, `abortPendingAuth`,
`PendingAuthRequest`, `revokeAuthToken`, `revokeActiveConnectionsForToken`)
no longer re-export from `devframe/node` — import from `devframe/node/auth`.

The `devframe/internal` sub-export is renamed to `devframe/node/internal`,
which also now hosts the relocated `context-internal.ts`. End users were
never meant to depend on this subpath; first-party adapters update accordingly.
diff --git a/AGENTS.md b/AGENTS.md
@@ -45,7 +45,7 @@ flowchart TD
 
 `devframe/packages/devframe` is the lowest-level package in this monorepo and is positioned to be extracted into its own repo. It MUST NOT import from `vite`, `@vitejs/*`, or any hub-only concept (docks, terminals, messages, commands) — not as a `dependencies` entry, not as an inlined dep, not as a source import. `packages/kit` and above build on top of devframe; never the reverse. If a feature requires multi-integration awareness, it goes in kit.
 
-`devframe/internal` is a marked-internal subpath that exposes a small set of helpers (`getInternalContext`, `resolveBasePath`) for first-party adapters that need to reach into devframe's private machinery — kit's relocated `DocksHost` uses it for remote-dock token allocation. End users should not import it.
+`devframe/node/internal` is a marked-internal subpath that exposes a small set of helpers (`getInternalContext`, `resolveBasePath`) for first-party adapters that need to reach into devframe's private machinery — kit's relocated `DocksHost` uses it for remote-dock token allocation. End users should not import it.
 
 ## Architecture
 
diff --git a/alias.ts b/alias.ts
@@ -13,9 +13,10 @@ export const alias = {
   'devframe/rpc/server': df('devframe/src/rpc/server.ts'),
   'devframe/rpc': df('devframe/src/rpc'),
   'devframe/types': df('devframe/src/types/index.ts'),
+  'devframe/node/auth': df('devframe/src/node/auth/index.ts'),
+  'devframe/node/internal': df('devframe/src/node/internal/index.ts'),
   'devframe/node': df('devframe/src/node/index.ts'),
   'devframe/constants': df('devframe/src/constants.ts'),
-  'devframe/internal': df('devframe/src/internal/index.ts'),
   'devframe/utils/colors': df('devframe/src/utils/colors.ts'),
   'devframe/utils/events': df('devframe/src/utils/events.ts'),
   'devframe/utils/hash': df('devframe/src/utils/hash.ts'),
diff --git a/devframe/packages/devframe/package.json b/devframe/packages/devframe/package.json
@@ -28,8 +28,9 @@
     "./adapters/vite": "./dist/adapters/vite.mjs",
     "./client": "./dist/client/index.mjs",
     "./constants": "./dist/constants.mjs",
-    "./internal": "./dist/internal/index.mjs",
     "./node": "./dist/node/index.mjs",
+    "./node/auth": "./dist/node/auth.mjs",
+    "./node/internal": "./dist/node/internal.mjs",
     "./recipes/open-helpers": "./dist/recipes/open-helpers.mjs",
     "./rpc": "./dist/rpc/index.mjs",
     "./rpc/client": "./dist/rpc/client.mjs",
diff --git a/devframe/packages/devframe/src/node/auth/index.ts b/devframe/packages/devframe/src/node/auth/index.ts
@@ -0,0 +1,2 @@
+export * from './revoke'
+export * from './state'
diff --git a/devframe/packages/devframe/src/node/auth/revoke.ts b/devframe/packages/devframe/src/node/auth/revoke.ts
@@ -1,7 +1,7 @@
 import type { DevToolsNodeContext } from 'devframe/types'
 import type { SharedState } from 'devframe/utils/shared-state'
-import type { InternalAnonymousAuthStorage } from './context-internal'
-import type { RpcFunctionsHost } from './host-functions'
+import type { RpcFunctionsHost } from '../host-functions'
+import type { InternalAnonymousAuthStorage } from '../internal/context'
 
 /**
  * Flip `isTrusted` to false on any live WS clients connected with `token`
diff --git a/devframe/packages/devframe/src/node/auth/state.ts b/devframe/packages/devframe/src/node/auth/state.ts
@@ -1,6 +1,6 @@
 import type { DevToolsNodeRpcSession } from 'devframe/types'
 import type { SharedState } from 'devframe/utils/shared-state'
-import type { InternalAnonymousAuthStorage } from './context-internal'
+import type { InternalAnonymousAuthStorage } from '../internal/context'
 import { humanId } from 'devframe/utils/human-id'
 
 export interface PendingAuthRequest {
diff --git a/devframe/packages/devframe/src/node/index.ts b/devframe/packages/devframe/src/node/index.ts
@@ -1,8 +1,5 @@
 // Node-side public API for consumers that wire up their own runtime.
-export * from './auth-revoke'
-export * from './auth-state'
 export * from './context'
-export * from './context-internal'
 export * from './host-agent'
 export * from './host-diagnostics'
 export * from './host-functions'
diff --git a/devframe/packages/devframe/src/node/internal/context.ts b/devframe/packages/devframe/src/node/internal/context.ts
@@ -2,8 +2,8 @@ import type { DevToolsNodeContext } from 'devframe/types'
 import type { SharedState } from 'devframe/utils/shared-state'
 import { humanId } from 'devframe/utils/human-id'
 import { join } from 'pathe'
-import { revokeActiveConnectionsForToken, revokeAuthToken } from './auth-revoke'
-import { createStorage } from './storage'
+import { revokeActiveConnectionsForToken, revokeAuthToken } from '../auth/revoke'
+import { createStorage } from '../storage'
 
 export interface InternalAnonymousAuthStorage {
   trusted: Record<string, {
diff --git a/devframe/packages/devframe/src/node/internal/index.ts b/devframe/packages/devframe/src/node/internal/index.ts
@@ -12,15 +12,15 @@
 export {
   normalizeBasePath,
   resolveBasePath,
-} from '../adapters/_shared'
+} from '../../adapters/_shared'
 
 export {
   getInternalContext,
   internalContextMap,
-} from '../node/context-internal'
+} from './context'
 
 export type {
   DevToolsInternalContext,
   InternalAnonymousAuthStorage,
   RemoteTokenRecord,
-} from '../node/context-internal'
+} from './context'
diff --git a/devframe/packages/devframe/tsdown.config.ts b/devframe/packages/devframe/tsdown.config.ts
@@ -10,8 +10,9 @@ export default defineConfig({
     'rpc/transports/ws-server': 'src/rpc/transports/ws-server.ts',
     'types/index': 'src/types/index.ts',
     'node/index': 'src/node/index.ts',
+    'node/auth': 'src/node/auth/index.ts',
+    'node/internal': 'src/node/internal/index.ts',
     'constants': 'src/constants.ts',
-    'internal/index': 'src/internal/index.ts',
     'utils/colors': 'src/utils/colors.ts',
     'utils/events': 'src/utils/events.ts',
     'utils/hash': 'src/utils/hash.ts',
diff --git a/devframe/tests/__snapshots__/tsnapi/devframe/internal.snapshot.js b/devframe/tests/__snapshots__/tsnapi/devframe/internal.snapshot.js
diff --git a/devframe/tests/__snapshots__/tsnapi/devframe/node.snapshot.d.ts b/devframe/tests/__snapshots__/tsnapi/devframe/node.snapshot.d.ts
@@ -22,17 +22,6 @@ export interface CreateStorageOptions<T extends object> {
   mergeInitialValue?: false | ((_: T, _: T) => T);
   debounce?: number;
 }
-export interface PendingAuthRequest {
-  clientAuthToken: string;
-  session: DevToolsNodeRpcSession;
-  ua: string;
-  origin: string;
-  resolve: (_: {
-    isTrusted: boolean;
-  }) => void;
-  abortController: AbortController;
-  timeout: ReturnType<typeof setTimeout>;
-}
 export interface StaticRpcDumpCollection {
   manifest: StaticRpcDumpManifest;
   files: Record<string, StaticRpcDumpFile>;
@@ -119,30 +108,17 @@ export declare class RpcFunctionsHost extends RpcFunctionsCollectorBase<DevTools
 // #endregion
 
 // #region Functions
-export declare function abortPendingAuth(): void;
 export declare function collectStaticRpcDump(_: Iterable<RpcFunctionDefinitionAny>, _: any): Promise<StaticRpcDumpCollection>;
-export declare function consumeTempAuthToken(_: string, _: SharedState<InternalAnonymousAuthStorage>): string | null;
 export declare function createH3DevToolsHost(_: CreateH3DevToolsHostOptions): DevToolsHost;
 export declare function createHostContext(_: CreateHostContextOptions): Promise<DevToolsNodeContext>;
 export declare function createRpcSharedStateServerHost(_: RpcFunctionsHost$1): RpcSharedStateHost;
 export declare function createRpcStreamingServerHost(_: RpcFunctionsHost$1): RpcStreamingHost;
 export declare function createStorage<T extends object>(_: CreateStorageOptions<T>): SharedState<T>;
-export declare function getPendingAuth(): PendingAuthRequest | null;
-export declare function getTempAuthToken(): string;
 export declare function isObject(_: unknown): value is Record<string, any>;
 export declare function normalizeHttpServerUrl(_: string, _: number | string): string;
-export declare function refreshTempAuthToken(): string;
-export declare function revokeActiveConnectionsForToken(_: DevToolsNodeContext, _: string): Promise<void>;
-export declare function revokeAuthToken(_: DevToolsNodeContext, _: SharedState<InternalAnonymousAuthStorage>, _: string): Promise<void>;
-export declare function setPendingAuth(_: PendingAuthRequest | null): void;
 // #endregion
 
 // #region Other
-export { DevToolsInternalContext }
-export { getInternalContext }
-export { InternalAnonymousAuthStorage }
-export { internalContextMap }
-export { RemoteTokenRecord }
 export { StartedServer }
 export { startHttpAndWs }
 export { StartHttpAndWsOptions }
diff --git a/devframe/tests/__snapshots__/tsnapi/devframe/node.snapshot.js b/devframe/tests/__snapshots__/tsnapi/devframe/node.snapshot.js
@@ -2,14 +2,8 @@
  * Generated by tsnapi — public API snapshot of `devframe/node`
  */
 // #region Functions
-export function abortPendingAuth() {}
-export function consumeTempAuthToken(_, _) {}
-export function getPendingAuth() {}
-export function getTempAuthToken() {}
 export function isObject(_) {}
 export function normalizeHttpServerUrl(_, _) {}
-export function refreshTempAuthToken() {}
-export function setPendingAuth(_) {}
 // #endregion
 
 // #region Other
@@ -22,10 +16,6 @@ export { createStorage }
 export { DevToolsAgentHost }
 export { DevToolsDiagnosticsHost }
 export { DevToolsViewHost }
-export { getInternalContext }
-export { internalContextMap }
-export { revokeActiveConnectionsForToken }
-export { revokeAuthToken }
 export { RpcFunctionsHost }
 export { startHttpAndWs }
 // #endregion
diff --git a/devframe/tests/__snapshots__/tsnapi/devframe/node/auth.snapshot.d.ts b/devframe/tests/__snapshots__/tsnapi/devframe/node/auth.snapshot.d.ts
@@ -0,0 +1,27 @@
+/**
+ * Generated by tsnapi — public API snapshot of `devframe/node/auth`
+ */
+// #region Interfaces
+export interface PendingAuthRequest {
+  clientAuthToken: string;
+  session: DevToolsNodeRpcSession;
+  ua: string;
+  origin: string;
+  resolve: (_: {
+    isTrusted: boolean;
+  }) => void;
+  abortController: AbortController;
+  timeout: ReturnType<typeof setTimeout>;
+}
+// #endregion
+
+// #region Functions
+export declare function abortPendingAuth(): void;
+export declare function consumeTempAuthToken(_: string, _: SharedState<InternalAnonymousAuthStorage>): string | null;
+export declare function getPendingAuth(): PendingAuthRequest | null;
+export declare function getTempAuthToken(): string;
+export declare function refreshTempAuthToken(): string;
+export declare function revokeActiveConnectionsForToken(_: DevToolsNodeContext, _: string): Promise<void>;
+export declare function revokeAuthToken(_: DevToolsNodeContext, _: SharedState<InternalAnonymousAuthStorage>, _: string): Promise<void>;
+export declare function setPendingAuth(_: PendingAuthRequest | null): void;
+// #endregion
diff --git a/devframe/tests/__snapshots__/tsnapi/devframe/node/auth.snapshot.js b/devframe/tests/__snapshots__/tsnapi/devframe/node/auth.snapshot.js
@@ -0,0 +1,16 @@
+/**
+ * Generated by tsnapi — public API snapshot of `devframe/node/auth`
+ */
+// #region Functions
+export function abortPendingAuth() {}
+export function consumeTempAuthToken(_, _) {}
+export function getPendingAuth() {}
+export function getTempAuthToken() {}
+export function refreshTempAuthToken() {}
+export function setPendingAuth(_) {}
+// #endregion
+
+// #region Other
+export { revokeActiveConnectionsForToken }
+export { revokeAuthToken }
+// #endregion
diff --git a/devframe/tests/__snapshots__/tsnapi/devframe/node/internal.snapshot.d.ts b/devframe/tests/__snapshots__/tsnapi/devframe/node/internal.snapshot.d.ts
@@ -1,5 +1,5 @@
 /**
- * Generated by tsnapi — public API snapshot of `devframe/internal`
+ * Generated by tsnapi — public API snapshot of `devframe/node/internal`
  */
 // #region Functions
 export declare function normalizeBasePath(_: string): string;
diff --git a/devframe/tests/__snapshots__/tsnapi/devframe/node/internal.snapshot.js b/devframe/tests/__snapshots__/tsnapi/devframe/node/internal.snapshot.js
@@ -0,0 +1,15 @@
+/**
+ * Generated by tsnapi — public API snapshot of `devframe/node/internal`
+ */
+// #region Functions
+export function getInternalContext(_) {}
+// #endregion
+
+// #region Variables
+export var internalContextMap /* const */
+// #endregion
+
+// #region Other
+export { normalizeBasePath }
+export { resolveBasePath }
+// #endregion
diff --git a/packages/core/src/index.ts b/packages/core/src/index.ts
@@ -2,4 +2,4 @@ export { createDevToolsContext } from './node/context'
 export { DevTools } from './node/plugins'
 export type { BuiltinServerFunctions } from './node/rpc'
 export { createDevToolsMiddleware } from './node/server'
-export type { DevToolsInternalContext, InternalAnonymousAuthStorage } from 'devframe/node'
+export type { DevToolsInternalContext, InternalAnonymousAuthStorage } from 'devframe/node/internal'
diff --git a/packages/core/src/internal.ts b/packages/core/src/internal.ts
@@ -1,2 +1,2 @@
-export { getInternalContext } from 'devframe/node'
-export type { DevToolsInternalContext, InternalAnonymousAuthStorage } from 'devframe/node'
+export { getInternalContext } from 'devframe/node/internal'
+export type { DevToolsInternalContext, InternalAnonymousAuthStorage } from 'devframe/node/internal'
diff --git a/packages/core/src/node/rpc/anonymous/auth.ts b/packages/core/src/node/rpc/anonymous/auth.ts
@@ -2,7 +2,8 @@
 import process from 'node:process'
 import * as p from '@clack/prompts'
 import { defineRpcFunction } from '@vitejs/devtools-kit'
-import { abortPendingAuth, getInternalContext, getTempAuthToken, refreshTempAuthToken, setPendingAuth } from 'devframe/node'
+import { abortPendingAuth, getTempAuthToken, refreshTempAuthToken, setPendingAuth } from 'devframe/node/auth'
+import { getInternalContext } from 'devframe/node/internal'
 import { colors as c } from 'devframe/utils/colors'
 import { MARK_INFO } from '../../constants'
 
diff --git a/packages/core/src/node/server.ts b/packages/core/src/node/server.ts
@@ -1,6 +1,7 @@
 import type { CreateWsServerOptions } from './ws'
 import { DEVTOOLS_CONNECTION_META_FILENAME } from '@vitejs/devtools-kit/constants'
-import { consumeTempAuthToken, getInternalContext } from 'devframe/node'
+import { consumeTempAuthToken } from 'devframe/node/auth'
+import { getInternalContext } from 'devframe/node/internal'
 import { serveStaticHandler } from 'devframe/utils/serve-static'
 import { createApp, eventHandler, getQuery, toNodeListener } from 'h3'
 import { dirClientStandalone } from '../dirs'
diff --git a/packages/core/src/node/ws.ts b/packages/core/src/node/ws.ts
@@ -4,7 +4,7 @@ import type { RpcFunctionsHost } from 'devframe/node'
 import type { WebSocket } from 'ws'
 import { AsyncLocalStorage } from 'node:async_hooks'
 import process from 'node:process'
-import { getInternalContext } from 'devframe/node'
+import { getInternalContext } from 'devframe/node/internal'
 import { createRpcServer } from 'devframe/rpc/server'
 import { attachWsRpcTransport } from 'devframe/rpc/transports/ws-server'
 import { colors as c } from 'devframe/utils/colors'
diff --git a/packages/kit/src/node/__tests__/host-docks.test.ts b/packages/kit/src/node/__tests__/host-docks.test.ts
@@ -2,7 +2,7 @@ import type { DevToolsDockUserEntry, DevToolsViewIframe, RemoteConnectionInfo }
 import type { KitNodeContext } from '../context'
 import { Buffer } from 'node:buffer'
 import { REMOTE_CONNECTION_KEY } from 'devframe/constants'
-import { getInternalContext, internalContextMap } from 'devframe/internal'
+import { getInternalContext, internalContextMap } from 'devframe/node/internal'
 import { describe, expect, it } from 'vitest'
 import { DevToolsDockHost } from '../host-docks'
 
diff --git a/packages/kit/src/node/create-plugin-from-devframe.ts b/packages/kit/src/node/create-plugin-from-devframe.ts
@@ -2,7 +2,7 @@ import type { DevframeDefinition, DevToolsCapabilities } from 'devframe/types'
 import type { DevToolsViewIframe } from '../types/docks'
 import type { PluginWithDevTools } from '../types/vite-augment'
 import type { KitNodeContext } from './context'
-import { resolveBasePath } from 'devframe/internal'
+import { resolveBasePath } from 'devframe/node/internal'
 import { resolve } from 'pathe'
 
 export interface CreatePluginFromDevframeOptions {
diff --git a/packages/kit/src/node/host-docks.ts b/packages/kit/src/node/host-docks.ts
@@ -12,8 +12,8 @@ import type {
 import type { DevToolsDocksUserSettings } from '../types/settings'
 import type { KitNodeContext } from './context'
 import { REMOTE_CONNECTION_KEY } from 'devframe/constants'
-import { getInternalContext } from 'devframe/internal'
 import { createStorage } from 'devframe/node'
+import { getInternalContext } from 'devframe/node/internal'
 import { createEventEmitter } from 'devframe/utils/events'
 import { join } from 'pathe'
 import { DEFAULT_STATE_USER_SETTINGS } from '../constants'
diff --git a/tsconfig.base.json b/tsconfig.base.json
@@ -27,15 +27,18 @@
       "devframe/types": [
         "./devframe/packages/devframe/src/types/index.ts"
       ],
+      "devframe/node/auth": [
+        "./devframe/packages/devframe/src/node/auth/index.ts"
+      ],
+      "devframe/node/internal": [
+        "./devframe/packages/devframe/src/node/internal/index.ts"
+      ],
       "devframe/node": [
         "./devframe/packages/devframe/src/node/index.ts"
       ],
       "devframe/constants": [
         "./devframe/packages/devframe/src/constants.ts"
       ],
-      "devframe/internal": [
-        "./devframe/packages/devframe/src/internal/index.ts"
-      ],
       "devframe/utils/colors": [
         "./devframe/packages/devframe/src/utils/colors.ts"
       ],

Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,2 @@`
	`1`	`+export * from './revoke'`
	`2`	`+export * from './state'`