devframe 0.0.0 → 0.1.17

package/dist/node/index.d.mts

@@ -0,0 +1,393 @@
+import { A as DevToolsViewHost$1, At as DevToolsDiagnosticsHost$1, Bt as DevToolsServerCommandEntry, F as DevToolsChildProcessTerminalSession, Ft as DevToolsCommandHandle, Gt as AgentResourceContent, H as DevToolsRpcClientFunctions, Ht as AgentHandle, I as DevToolsTerminalHost$1, Jt as AgentToolInput, Kt as AgentResourceInput, L as DevToolsTerminalSession, M as PartialWithoutId, P as DevToolsChildProcessExecuteOptions, R as DevToolsTerminalSessionBase, Rt as DevToolsCommandsHost$1, U as DevToolsRpcServerFunctions, Ut as AgentManifest, V as DevToolsDocksUserSettings, Vt as DevToolsServerCommandInput, Wt as AgentResource, Xt as DevToolsAgentHostEvents, Yt as DevToolsAgentHost$1, Zt as EventEmitter, _t as DevToolsDockUserEntry, at as DevToolsMessageHandle, ct as DevToolsMessagesHost$1, d as DevToolsNodeContext, ft as DevToolsDockEntry, g as RpcFunctionsHost$1, gt as DevToolsDockHost$1, h as RpcBroadcastOptions, jt as DevToolsDiagnosticsLogger, lt as DevToolsHost, m as DevToolsNodeRpcSession, qt as AgentTool, rt as DevToolsMessageEntryInput, tt as DevToolsMessageEntry, ut as ClientScriptEntry, v as RpcSharedStateHost, w as SharedState } from "../devtool-CHT-4_OU.mjs";
+import { g as RpcFunctionsCollectorBase } from "../index-Cei8vVcd.mjs";
+import { g as RpcFunctionDefinitionAny } from "../types-BkyzI9r4.mjs";
+import { createLogger, defineDiagnostics } from "logs-sdk";
+import { BirpcGroup } from "birpc";
+import { WebSocketServer } from "ws";
+import { AsyncLocalStorage } from "node:async_hooks";
+import { App } from "h3";
+
+//#region src/node/context-internal.d.ts
+interface InternalAnonymousAuthStorage {
+  trusted: Record<string, {
+    authToken: string;
+    ua: string;
+    origin: string;
+    timestamp: number;
+  } | undefined>;
+}
+interface RemoteTokenRecord {
+  dockId: string;
+  /** Dock URL origin — matched against WS handshake `Origin` header when `originLock` is on. */
+  origin: string;
+  originLock: boolean;
+}
+interface DevToolsInternalContext {
+  storage: {
+    auth: SharedState<InternalAnonymousAuthStorage>;
+  };
+  /**
+   * Revoke an auth token: remove from storage and notify all connected clients
+   * using this token that they are no longer trusted.
+   */
+  revokeAuthToken: (token: string) => Promise<void>;
+  /**
+   * Session-only tokens issued to remote-UI iframe docks. Not persisted —
+   * regenerated on every dev-server restart.
+   */
+  remoteTokens: Map<string, RemoteTokenRecord>;
+  allocateRemoteToken: (dockId: string, origin: string, originLock: boolean) => string;
+  revokeRemoteToken: (token: string) => void;
+  revokeRemoteTokensForDock: (dockId: string) => void;
+  /**
+   * Returns true if `token` is a valid remote token and, when `originLock` is
+   * on, `requestOrigin` matches the recorded dock origin.
+   */
+  isRemoteTokenTrusted: (token: string, requestOrigin?: string) => boolean;
+  /**
+   * Populated by `createWsServer` once the WS port is bound. Consumed by the
+   * docks host when enriching remote iframe URLs with a connection descriptor.
+   */
+  wsEndpoint?: {
+    /** Full `ws://` or `wss://` URL with host and port. */url: string;
+  };
+}
+declare const internalContextMap: WeakMap<DevToolsNodeContext, DevToolsInternalContext>;
+declare function getInternalContext(context: DevToolsNodeContext): DevToolsInternalContext;
+//#endregion
+//#region src/node/auth-revoke.d.ts
+/**
+ * Flip `isTrusted` to false on any live WS clients connected with `token`
+ * and broadcast the `auth:revoked` event so they can react.
+ *
+ * Shared between persisted-auth revocation and remote-dock token revocation.
+ */
+declare function revokeActiveConnectionsForToken(context: DevToolsNodeContext, token: string): Promise<void>;
+/**
+ * Revoke an auth token: remove from storage and notify all connected clients
+ * using this token that they are no longer trusted.
+ */
+declare function revokeAuthToken(context: DevToolsNodeContext, storage: SharedState<InternalAnonymousAuthStorage>, token: string): Promise<void>;
+//#endregion
+//#region src/node/auth-state.d.ts
+interface PendingAuthRequest {
+  clientAuthToken: string;
+  session: DevToolsNodeRpcSession;
+  ua: string;
+  origin: string;
+  resolve: (result: {
+    isTrusted: boolean;
+  }) => void;
+  abortController: AbortController;
+  timeout: ReturnType<typeof setTimeout>;
+}
+declare function getTempAuthToken(): string;
+declare function refreshTempAuthToken(): string;
+declare function getPendingAuth(): PendingAuthRequest | null;
+declare function setPendingAuth(request: PendingAuthRequest | null): void;
+/**
+ * Abort and clean up any existing pending auth request.
+ */
+declare function abortPendingAuth(): void;
+/**
+ * Consume the temp auth ID: verify it matches, trust the pending client, and clean up.
+ * Returns the client's authToken if successful, null otherwise.
+ */
+declare function consumeTempAuthToken(id: string, storage: SharedState<InternalAnonymousAuthStorage>): string | null;
+//#endregion
+//#region src/node/context.d.ts
+interface CreateHostContextOptions {
+  cwd: string;
+  workspaceRoot?: string;
+  mode: 'dev' | 'build';
+  host: DevToolsHost;
+  /**
+   * Built-in RPC declarations to register on the host. Framework
+   * adapters (vite, rolldown, cli) can pass the ones they need; the
+   * host itself has no opinions about the built-in set.
+   */
+  builtinRpcDeclarations?: readonly RpcFunctionDefinitionAny[];
+}
+/**
+ * Framework-neutral core of the DevTools node context. Wires the six
+ * host subsystems, the JSON-render factory, and the standard shared-state
+ * bookkeeping. Framework-specific extensions (Vite plugin scan, Vite
+ * config/server fields, built-in RPCs like `open-in-editor`) layer on
+ * top via wrapper functions such as kit's `createDevToolsContext`.
+ */
+declare function createHostContext(options: CreateHostContextOptions): Promise<DevToolsNodeContext>;
+//#endregion
+//#region src/node/context-utils.d.ts
+declare const ContextUtils: {
+  createSimpleClientScript(fn: string | ((ctx: any) => void)): ClientScriptEntry;
+};
+//#endregion
+//#region src/node/host-agent.d.ts
+/**
+ * Framework-neutral host aggregating the agent-exposed surface of a
+ * devtool. Auto-discovers RPC functions with an `agent` field from
+ * `ctx.rpc.definitions`, and accepts plugin-registered tools /
+ * resources via `registerTool` / `registerResource`.
+ *
+ * @experimental
+ */
+declare class DevToolsAgentHost implements DevToolsAgentHost$1 {
+  readonly context: DevToolsNodeContext;
+  readonly events: EventEmitter<DevToolsAgentHostEvents>;
+  private readonly tools;
+  private readonly resources;
+  private _rpcUnsubscribe;
+  constructor(context: DevToolsNodeContext);
+  registerTool(input: AgentToolInput): AgentHandle;
+  unregisterTool(id: string): boolean;
+  registerResource(input: AgentResourceInput): AgentHandle;
+  unregisterResource(id: string): boolean;
+  list(): AgentManifest;
+  getTool(id: string): AgentTool | undefined;
+  getResource(id: string): AgentResource | undefined;
+  invoke(id: string, args: unknown): Promise<unknown>;
+  read(id: string): Promise<AgentResourceContent>;
+  /** @internal */
+  _dispose(): void;
+  private _validateToolId;
+  private _projectTool;
+  private _collectRpcTools;
+  private _findRpcDefinition;
+  private _coercePositionalArgs;
+}
+//#endregion
+//#region src/node/host-commands.d.ts
+declare class DevToolsCommandsHost implements DevToolsCommandsHost$1 {
+  readonly context: DevToolsNodeContext;
+  readonly commands: DevToolsCommandsHost$1['commands'];
+  readonly events: DevToolsCommandsHost$1['events'];
+  constructor(context: DevToolsNodeContext);
+  register(command: DevToolsServerCommandInput): DevToolsCommandHandle;
+  unregister(id: string): boolean;
+  execute(id: string, ...args: any[]): Promise<unknown>;
+  list(): DevToolsServerCommandEntry[];
+  private findCommand;
+  private toSerializable;
+}
+//#endregion
+//#region src/node/host-diagnostics.d.ts
+declare class DevToolsDiagnosticsHost implements DevToolsDiagnosticsHost$1 {
+  readonly context: DevToolsNodeContext;
+  private _definitions;
+  private _logger;
+  readonly defineDiagnostics: typeof defineDiagnostics;
+  readonly createLogger: typeof createLogger;
+  constructor(context: DevToolsNodeContext, initialDefinitions?: unknown[]);
+  get logger(): DevToolsDiagnosticsLogger;
+  register(definitions: unknown): void;
+  private _rebuild;
+}
+//#endregion
+//#region src/node/host-docks.d.ts
+declare class DevToolsDockHost implements DevToolsDockHost$1 {
+  readonly context: DevToolsNodeContext;
+  readonly views: DevToolsDockHost$1['views'];
+  readonly events: DevToolsDockHost$1['events'];
+  userSettings: SharedState<DevToolsDocksUserSettings>;
+  /** Dock-id → allocated remote token + resolved options. */
+  private readonly remoteDocks;
+  constructor(context: DevToolsNodeContext);
+  init(): Promise<void>;
+  values({
+    includeBuiltin
+  }?: {
+    includeBuiltin?: boolean;
+  }): DevToolsDockEntry[];
+  private projectView;
+  private resolveDevServerOrigin;
+  register<T extends DevToolsDockUserEntry>(view: T, force?: boolean): {
+    update: (patch: Partial<T>) => void;
+  };
+  update(view: DevToolsDockUserEntry): void;
+  private prepareRemoteRegistration;
+}
+//#endregion
+//#region src/node/host-functions.d.ts
+declare class RpcFunctionsHost extends RpcFunctionsCollectorBase<DevToolsRpcServerFunctions, DevToolsNodeContext> implements RpcFunctionsHost$1 {
+  /**
+   * @internal
+   */
+  _rpcGroup: BirpcGroup<DevToolsRpcClientFunctions, DevToolsRpcServerFunctions, false>;
+  _asyncStorage: AsyncLocalStorage<DevToolsNodeRpcSession>;
+  constructor(context: DevToolsNodeContext);
+  sharedState: RpcSharedStateHost;
+  invokeLocal<T extends keyof DevToolsRpcServerFunctions, Args extends Parameters<DevToolsRpcServerFunctions[T]>>(method: T, ...args: Args): Promise<Awaited<ReturnType<DevToolsRpcServerFunctions[T]>>>;
+  broadcast<T extends keyof DevToolsRpcClientFunctions, Args extends Parameters<DevToolsRpcClientFunctions[T]>>(options: RpcBroadcastOptions<T, Args>): Promise<void>;
+  getCurrentRpcSession(): DevToolsNodeRpcSession | undefined;
+}
+//#endregion
+//#region src/node/host-h3.d.ts
+interface CreateH3DevToolsHostOptions {
+  /** The h3 app instance — registered once the CLI adapter lands. */
+  app?: unknown;
+  /**
+   * Host the standalone server listens on, e.g. `http://localhost:9999`.
+   * Consumed by `resolveOrigin` for dock entries that need an absolute URL.
+   */
+  origin: string;
+  /**
+   * Register a static-file handler at `base` serving files from `distDir`.
+   * Wired into the h3 app once the CLI adapter lands (commit 5). For now
+   * the CLI isn't running, so the default is a no-op.
+   */
+  mount?: (base: string, distDir: string) => void | Promise<void>;
+}
+/**
+ * h3-backed {@link DevToolsHost} — used by the standalone CLI adapter.
+ * This commit adds the shell; the CLI adapter in commit 5 wires it up
+ * with a real h3 app and sirv handler.
+ */
+declare function createH3DevToolsHost(options: CreateH3DevToolsHostOptions): DevToolsHost;
+//#endregion
+//#region src/node/host-messages.d.ts
+declare class DevToolsMessagesHost implements DevToolsMessagesHost$1 {
+  readonly context: DevToolsNodeContext;
+  readonly entries: DevToolsMessagesHost$1['entries'];
+  readonly events: DevToolsMessagesHost$1['events'];
+  /** Tracks when each entry was last added or updated (monotonic) */
+  readonly lastModified: Map<string, number>;
+  /** Tracks recently removed entry IDs with their removal time */
+  readonly removals: Array<{
+    id: string;
+    time: number;
+  }>;
+  private _autoDeleteTimers;
+  private _clock;
+  private _tick;
+  constructor(context: DevToolsNodeContext);
+  add(input: DevToolsMessageEntryInput): Promise<DevToolsMessageHandle>;
+  update(id: string, patch: Partial<DevToolsMessageEntryInput>): Promise<DevToolsMessageEntry | undefined>;
+  remove(id: string): Promise<void>;
+  clear(): Promise<void>;
+  private _createHandle;
+}
+//#endregion
+//#region src/node/host-terminals.d.ts
+declare class DevToolsTerminalHost implements DevToolsTerminalHost$1 {
+  readonly context: DevToolsNodeContext;
+  readonly sessions: DevToolsTerminalHost$1['sessions'];
+  readonly events: DevToolsTerminalHost$1['events'];
+  private _boundStreams;
+  constructor(context: DevToolsNodeContext);
+  register(session: DevToolsTerminalSession): DevToolsTerminalSession;
+  update(patch: PartialWithoutId<DevToolsTerminalSession>): void;
+  remove(session: DevToolsTerminalSession): void;
+  private bindStream;
+  startChildProcess(executeOptions: DevToolsChildProcessExecuteOptions, terminal: Omit<DevToolsTerminalSessionBase, 'status'>): Promise<DevToolsChildProcessTerminalSession>;
+}
+//#endregion
+//#region src/node/host-views.d.ts
+declare class DevToolsViewHost implements DevToolsViewHost$1 {
+  readonly context: DevToolsNodeContext;
+  /**
+   * @internal
+   */
+  buildStaticDirs: {
+    baseUrl: string;
+    distDir: string;
+  }[];
+  constructor(context: DevToolsNodeContext);
+  hostStatic(baseUrl: string, distDir: string): void;
+}
+//#endregion
+//#region src/node/rpc-shared-state.d.ts
+declare function createRpcSharedStateServerHost(rpc: RpcFunctionsHost$1): RpcSharedStateHost;
+//#endregion
+//#region src/node/server.d.ts
+interface StartHttpAndWsOptions {
+  context: DevToolsNodeContext;
+  host?: string;
+  port: number;
+  /**
+   * Optional h3 app to mount on. When omitted a fresh one is created;
+   * when provided, callers can add their own routes (sirv etc.) first.
+   */
+  app?: App;
+  /**
+   * When `false`, the RPC server is started without a trust handshake.
+   * Intended for single-user localhost tools where an auth round-trip
+   * would only get in the way. The Vite-flavoured auth layer in
+   * `@vitejs/devtools` already honors the equivalent
+   * `devtools.clientAuth` setting; devframe records the intent here so
+   * future auth plumbing can consult it without another API change.
+   *
+   * Default: `true`.
+   */
+  auth?: boolean;
+  /**
+   * Called once the WS server is bound so callers can mount static
+   * handlers whose origin depends on the resolved port, or print their
+   * own startup banner. Devframe does not print one itself.
+   */
+  onReady?: (info: {
+    origin: string;
+    port: number;
+    app: App;
+  }) => void | Promise<void>;
+}
+interface StartedServer {
+  /** Listening origin, e.g. `http://localhost:9999`. */
+  origin: string;
+  port: number;
+  app: App;
+  wss: WebSocketServer;
+  rpcGroup: BirpcGroup<DevToolsRpcClientFunctions, DevToolsRpcServerFunctions, false>;
+  close: () => Promise<void>;
+}
+/**
+ * Compose an h3 + WebSocket server for a devtool context. The RPC
+ * group is bound to `context.rpc.functions`; the WS endpoint lives on
+ * the same port as the HTTP server.
+ */
+declare function startHttpAndWs(options: StartHttpAndWsOptions): Promise<StartedServer>;
+//#endregion
+//#region src/node/static-dump.d.ts
+type StaticRpcDumpSerialization = 'json' | 'structured-clone';
+interface StaticRpcDumpManifestStaticEntry {
+  type: 'static';
+  path: string;
+  /** Encoder used when this entry's file was written. Default: `'json'`. */
+  serialization?: StaticRpcDumpSerialization;
+}
+interface StaticRpcDumpManifestQueryEntry {
+  type: 'query';
+  records: Record<string, string>;
+  fallback?: string;
+  /** Encoder used when each record/fallback file was written. Default: `'json'`. */
+  serialization?: StaticRpcDumpSerialization;
+}
+type StaticRpcDumpManifestValue = StaticRpcDumpManifestStaticEntry | StaticRpcDumpManifestQueryEntry | any;
+type StaticRpcDumpManifest = Record<string, StaticRpcDumpManifestValue>;
+interface StaticRpcDumpFile {
+  /** Whether this file was written via `JSON.stringify` or `structured-clone-es.stringify`. */
+  serialization: StaticRpcDumpSerialization;
+  /** Function name the file belongs to — used to scope `DF0019` errors during write. */
+  fnName: string;
+  /** Payload to encode. */
+  data: unknown;
+}
+interface StaticRpcDumpCollection {
+  manifest: StaticRpcDumpManifest;
+  files: Record<string, StaticRpcDumpFile>;
+}
+declare function collectStaticRpcDump(definitions: Iterable<RpcFunctionDefinitionAny>, context: any): Promise<StaticRpcDumpCollection>;
+//#endregion
+//#region src/node/storage.d.ts
+interface CreateStorageOptions<T extends object> {
+  filepath: string;
+  initialValue: T;
+  mergeInitialValue?: false | ((initialValue: T, savedValue: T) => T);
+  debounce?: number;
+}
+declare function createStorage<T extends object>(options: CreateStorageOptions<T>): SharedState<T>;
+//#endregion
+//#region src/node/utils.d.ts
+declare function isObject(value: unknown): value is Record<string, any>;
+declare function normalizeHttpServerUrl(host: string, port: number | string): string;
+//#endregion
+export { ContextUtils, CreateH3DevToolsHostOptions, CreateHostContextOptions, CreateStorageOptions, DevToolsAgentHost, DevToolsCommandsHost, DevToolsDiagnosticsHost, DevToolsDockHost, DevToolsInternalContext, DevToolsMessagesHost, DevToolsTerminalHost, DevToolsViewHost, InternalAnonymousAuthStorage, PendingAuthRequest, RemoteTokenRecord, RpcFunctionsHost, StartHttpAndWsOptions, StartedServer, StaticRpcDumpCollection, StaticRpcDumpFile, StaticRpcDumpManifest, StaticRpcDumpManifestQueryEntry, StaticRpcDumpManifestStaticEntry, StaticRpcDumpManifestValue, StaticRpcDumpSerialization, abortPendingAuth, collectStaticRpcDump, consumeTempAuthToken, createH3DevToolsHost, createHostContext, createRpcSharedStateServerHost, createStorage, getInternalContext, getPendingAuth, getTempAuthToken, internalContextMap, isObject, normalizeHttpServerUrl, refreshTempAuthToken, revokeActiveConnectionsForToken, revokeAuthToken, setPendingAuth, startHttpAndWs };

package/dist/node/index.mjs

@@ -0,0 +1,69 @@
+import { t as import_dist } from "../human-id-CHS0s28X.mjs";
+import { _ as revokeAuthToken, a as RpcFunctionsHost, c as getInternalContext, d as DevToolsDiagnosticsHost, f as DevToolsCommandsHost, g as revokeActiveConnectionsForToken, h as ContextUtils, i as DevToolsMessagesHost, l as internalContextMap, n as DevToolsViewHost, o as createRpcSharedStateServerHost, p as DevToolsAgentHost, r as DevToolsTerminalHost, s as DevToolsDockHost, t as createHostContext, u as createStorage } from "../context-xQo1FcxX.mjs";
+import { n as createH3DevToolsHost, t as collectStaticRpcDump } from "../static-dump-DwFfj4U_.mjs";
+import { t as startHttpAndWs } from "../server-DkJ2-s0Y.mjs";
+import { isIP } from "node:net";
+//#region src/node/auth-state.ts
+let pendingAuth = null;
+let tempAuthToken = generateTempId();
+function generateTempId() {
+	return (0, import_dist.humanId)({
+		separator: "-",
+		capitalize: false
+	});
+}
+function getTempAuthToken() {
+	return tempAuthToken;
+}
+function refreshTempAuthToken() {
+	tempAuthToken = generateTempId();
+	return tempAuthToken;
+}
+function getPendingAuth() {
+	return pendingAuth;
+}
+function setPendingAuth(request) {
+	pendingAuth = request;
+}
+/**
+* Abort and clean up any existing pending auth request.
+*/
+function abortPendingAuth() {
+	if (pendingAuth) {
+		pendingAuth.abortController.abort();
+		clearTimeout(pendingAuth.timeout);
+		pendingAuth = null;
+	}
+}
+/**
+* Consume the temp auth ID: verify it matches, trust the pending client, and clean up.
+* Returns the client's authToken if successful, null otherwise.
+*/
+function consumeTempAuthToken(id, storage) {
+	if (id !== tempAuthToken || !pendingAuth) return null;
+	const { clientAuthToken, session, ua, origin, resolve } = pendingAuth;
+	storage.mutate((state) => {
+		state.trusted[clientAuthToken] = {
+			authToken: clientAuthToken,
+			ua,
+			origin,
+			timestamp: Date.now()
+		};
+	});
+	session.meta.clientAuthToken = clientAuthToken;
+	session.meta.isTrusted = true;
+	resolve({ isTrusted: true });
+	abortPendingAuth();
+	refreshTempAuthToken();
+	return clientAuthToken;
+}
+//#endregion
+//#region src/node/utils.ts
+function isObject(value) {
+	return Object.prototype.toString.call(value) === "[object Object]";
+}
+function normalizeHttpServerUrl(host, port) {
+	return `http://${host === "127.0.0.1" ? "localhost" : isIP(host) === 6 ? `[${host}]` : host}:${port}`;
+}
+//#endregion
+export { ContextUtils, DevToolsAgentHost, DevToolsCommandsHost, DevToolsDiagnosticsHost, DevToolsDockHost, DevToolsMessagesHost, DevToolsTerminalHost, DevToolsViewHost, RpcFunctionsHost, abortPendingAuth, collectStaticRpcDump, consumeTempAuthToken, createH3DevToolsHost, createHostContext, createRpcSharedStateServerHost, createStorage, getInternalContext, getPendingAuth, getTempAuthToken, internalContextMap, isObject, normalizeHttpServerUrl, refreshTempAuthToken, revokeActiveConnectionsForToken, revokeAuthToken, setPendingAuth, startHttpAndWs };