devframe 0.0.0 → 0.1.16

package/dist/devtool-OJ3QW0ns.d.mts

@@ -0,0 +1,1125 @@
+import { u as RpcFunctionsCollectorBase } from "./index-DvKDO5H8.mjs";
+import { t as DevToolsNodeRpcSessionMeta } from "./ws-server--IuUAaGi.mjs";
+import { GenericSchema, InferOutput } from "valibot";
+import { BirpcReturn } from "birpc";
+import { CAC } from "cac";
+import { ChildProcess } from "node:child_process";
+
+//#region src/adapters/flags.d.ts
+/**
+ * Schema map for typed CLI flags. Keys are flag names in camelCase —
+ * this matches CAC's parsed-flag output ( `--no-open` → `noOpen` ). Each
+ * value is a valibot schema used to both (a) derive the CAC option type
+ * when the flag is registered and (b) validate / coerce the parsed
+ * value before it's forwarded to `setup(ctx, { flags })`.
+ */
+type CliFlagsSchema = Record<string, GenericSchema>;
+/**
+ * Identity helper that preserves the literal schema-map type — use this
+ * so `InferCliFlags<typeof myFlags>` resolves to the right object shape.
+ *
+ * ```ts
+ * const appFlags = defineCliFlags({
+ *   depth: v.pipe(v.number(), v.integer()),
+ *   config: v.optional(v.string()),
+ * })
+ *
+ * defineDevtool({
+ *   cli: { flags: appFlags },
+ *   setup(ctx, info) {
+ *     const flags = info.flags as InferCliFlags<typeof appFlags>
+ *     flags.depth // number
+ *     flags.config // string | undefined
+ *   },
+ * })
+ * ```
+ */
+declare function defineCliFlags<T extends CliFlagsSchema>(flags: T): T;
+/** Extract the parsed-output type from a {@link CliFlagsSchema}. */
+type InferCliFlags<T extends CliFlagsSchema> = { [K in keyof T]: InferOutput<T[K]> };
+//#endregion
+//#region src/types/events.d.ts
+interface EventsMap {
+  [event: string]: any;
+}
+interface EventUnsubscribe {
+  (): void;
+}
+interface EventEmitter<Events extends EventsMap> {
+  /**
+   * Calls each of the listeners registered for a given event.
+   *
+   * ```js
+   * ee.emit('tick', tickType, tickDuration)
+   * ```
+   *
+   * @param event The event name.
+   * @param args The arguments for listeners.
+   */
+  emit: <K extends keyof Events>(event: K, ...args: Parameters<Events[K]>) => void;
+  /**
+   * Calls the listeners for a given event once and then removes the listener.
+   *
+   * @param event The event name.
+   * @param args The arguments for listeners.
+   */
+  emitOnce: <K extends keyof Events>(event: K, ...args: Parameters<Events[K]>) => void;
+  /**
+   * Event names in keys and arrays with listeners in values.
+   *
+   * @internal
+   */
+  _listeners: Partial<{ [E in keyof Events]: Events[E][] }>;
+  /**
+   * Add a listener for a given event.
+   *
+   * ```js
+   * const unbind = ee.on('tick', (tickType, tickDuration) => {
+   *   count += 1
+   * })
+   *
+   * disable () {
+   *   unbind()
+   * }
+   * ```
+   *
+   * @param event The event name.
+   * @param cb The listener function.
+   * @returns Unbind listener from event.
+   */
+  on: <K extends keyof Events>(event: K, cb: Events[K]) => EventUnsubscribe;
+  /**
+   * Add a listener for a given event once.
+   *
+   * ```js
+   * const unbind = ee.once('tick', (tickType, tickDuration) => {
+   *   count += 1
+   * })
+   *
+   * disable () {
+   *   unbind()
+   * }
+   * ```
+   *
+   * @param event The event name.
+   * @param cb The listener function.
+   * @returns Unbind listener from event.
+   */
+  once: <K extends keyof Events>(event: K, cb: Events[K]) => EventUnsubscribe;
+}
+//#endregion
+//#region src/types/agent.d.ts
+/**
+ * Serializable description of an agent-exposed tool. This is the shape
+ * returned by the agent host manifest and surfaced over the wire by
+ * the `devframe:agent:list-tools` introspection RPC.
+ *
+ * @experimental The agent-native surface is experimental and may change
+ * without a major version bump until it stabilizes.
+ */
+interface AgentTool {
+  /** Stable identifier. For RPC-backed tools, matches the RPC name. */
+  id: string;
+  /** `'rpc'` when backed by a registered RPC function, `'tool'` when registered via `ctx.agent.registerTool()`. */
+  kind: 'rpc' | 'tool';
+  /** Display title (falls back to `id`). */
+  title: string;
+  /** Human-readable description shown to the agent. */
+  description: string;
+  /** Safety classification — drives MCP hint annotations downstream. */
+  safety: 'read' | 'action' | 'destructive';
+  /** Free-form tags for grouping/filtering. */
+  tags?: readonly string[];
+  /** Present for `kind === 'rpc'` — points to the RPC function name. */
+  rpcName?: string;
+  /** JSON Schema describing the input (positional args synthesized to an object). */
+  inputSchema?: unknown;
+  /** JSON Schema describing the output. */
+  outputSchema?: unknown;
+  /** Example invocations shown to agents. */
+  examples?: readonly {
+    args: unknown[];
+    description?: string;
+  }[];
+}
+/**
+ * Input accepted by `DevToolsAgentHost.registerTool()`. Handler is
+ * stripped from the serializable `AgentTool` projection.
+ *
+ * @experimental
+ */
+interface AgentToolInput {
+  id: string;
+  title?: string;
+  description: string;
+  safety?: 'read' | 'action' | 'destructive';
+  tags?: readonly string[];
+  inputSchema?: unknown;
+  outputSchema?: unknown;
+  examples?: readonly {
+    args: unknown[];
+    description?: string;
+  }[];
+  /** Invoked when the tool is called. Receives args as provided by the caller. */
+  handler: (args: any) => unknown | Promise<unknown>;
+}
+/**
+ * Serializable description of an agent-readable resource. Resources
+ * surface structured or textual snapshots of devtools state.
+ *
+ * @experimental
+ */
+interface AgentResource {
+  id: string;
+  /** URI used by MCP clients. Defaults to `devframe://resource/<id>`. */
+  uri: string;
+  name: string;
+  description?: string;
+  /** Defaults to `application/json`. */
+  mimeType?: string;
+}
+/**
+ * Input accepted by `DevToolsAgentHost.registerResource()`.
+ *
+ * @experimental
+ */
+interface AgentResourceInput {
+  id: string;
+  name: string;
+  description?: string;
+  mimeType?: string;
+  /** Optional URI override — if omitted, a `devframe://resource/<id>` URI is generated. */
+  uri?: string;
+  /** Snapshot reader. Called on each read. */
+  read: () => Promise<AgentResourceContent> | AgentResourceContent;
+}
+/**
+ * Payload returned by `AgentResourceInput.read`. Either `text` or `json` must be set.
+ *
+ * @experimental
+ */
+interface AgentResourceContent {
+  text?: string;
+  json?: unknown;
+  /** Override the resource's declared mimeType for this read. */
+  mimeType?: string;
+}
+/**
+ * Unified view of the agent-exposed surface.
+ *
+ * @experimental
+ */
+interface AgentManifest {
+  tools: readonly AgentTool[];
+  resources: readonly AgentResource[];
+}
+/**
+ * Handle returned by `registerTool` / `registerResource`.
+ *
+ * @experimental
+ */
+interface AgentHandle {
+  unregister: () => void;
+}
+/**
+ * Events emitted by `DevToolsAgentHost`.
+ *
+ * @experimental
+ */
+interface DevToolsAgentHostEvents {
+  'agent:tool:registered': (tool: AgentTool) => void;
+  'agent:tool:unregistered': (id: string) => void;
+  'agent:resource:registered': (resource: AgentResource) => void;
+  'agent:resource:unregistered': (id: string) => void;
+  /**
+   * Fires when the unified manifest changes — including when a new
+   * RPC function with an `agent` field is registered on `ctx.rpc`.
+   */
+  'agent:manifest:changed': () => void;
+}
+/**
+ * Host that aggregates the agent-exposed surface of a devtool: both
+ * RPC functions flagged with `agent` and plugin-registered tools /
+ * resources. Consumed by protocol adapters such as the devframe MCP
+ * adapter.
+ *
+ * @experimental The agent-native surface is experimental and may change
+ * without a major version bump until it stabilizes.
+ */
+interface DevToolsAgentHost {
+  readonly events: EventEmitter<DevToolsAgentHostEvents>;
+  /**
+   * Register a tool not backed by an RPC function. Use this when you
+   * want a plain agent action (e.g. a synthesized summary) that
+   * shouldn't exist as a full RPC.
+   */
+  registerTool: (tool: AgentToolInput) => AgentHandle;
+  /** Unregister a previously registered tool by id. */
+  unregisterTool: (id: string) => boolean;
+  /** Register a readable resource. */
+  registerResource: (resource: AgentResourceInput) => AgentHandle;
+  /** Unregister a previously registered resource by id. */
+  unregisterResource: (id: string) => boolean;
+  /**
+   * Unified snapshot of agent-exposed surface: RPC functions with an
+   * `agent` field (auto-discovered from `ctx.rpc.definitions`) plus
+   * tools/resources registered on the host.
+   */
+  list: () => AgentManifest;
+  /**
+   * Invoke any tool by id. Routes to the underlying RPC handler for
+   * `kind === 'rpc'`, or to the registered handler for `kind === 'tool'`.
+   */
+  invoke: (id: string, args: unknown) => Promise<unknown>;
+  /** Read a resource by id. */
+  read: (id: string) => Promise<AgentResourceContent>;
+  /** Look up a tool by id (returns the serializable projection). */
+  getTool: (id: string) => AgentTool | undefined;
+  /** Look up a resource by id. */
+  getResource: (id: string) => AgentResource | undefined;
+}
+//#endregion
+//#region src/types/commands.d.ts
+interface DevToolsCommandKeybinding {
+  /**
+   * Keyboard shortcut string.
+   * Use "Mod" for platform-aware modifier (Cmd on macOS, Ctrl elsewhere).
+   * Examples: "Mod+K", "Mod+Shift+P", "Alt+N"
+   */
+  key: string;
+}
+interface DevToolsCommandBase {
+  /**
+   * Unique namespaced ID, e.g. "vite:open-in-editor"
+   */
+  id: string;
+  title: string;
+  description?: string;
+  /**
+   * Iconify icon string, e.g. "ph:pencil-duotone"
+   */
+  icon?: string;
+  category?: string;
+  /**
+   * Whether to show in command palette. Default: true
+   *
+   * - `true` — show the command and flatten its children into search results
+   * - `false` — hide the command entirely from the palette
+   * - `'without-children'` — show the command but don't flatten children into top-level search (children are still accessible via drill-down)
+   */
+  showInPalette?: boolean | 'without-children';
+  /**
+   * Optional context expression for conditional visibility.
+   * When set, the command is only shown in the palette and only executable
+   * when the expression evaluates to true.
+   *
+   * Uses the same syntax as keybinding `when` clauses.
+   * @example 'clientType == embedded'
+   * @example 'dockOpen && !paletteOpen'
+   */
+  when?: string;
+  /**
+   * Default keyboard shortcut(s) for this command
+   */
+  keybindings?: DevToolsCommandKeybinding[];
+}
+/**
+ * Server command input — what plugins pass to `ctx.commands.register()`.
+ */
+interface DevToolsServerCommandInput extends DevToolsCommandBase {
+  /**
+   * Handler for this command. Optional if the command only serves as a group for children.
+   */
+  handler?: (...args: any[]) => any | Promise<any>;
+  /**
+   * Static sub-commands. Two levels max (parent → children).
+   * Each child must have a globally unique `id`.
+   */
+  children?: DevToolsServerCommandInput[];
+}
+/**
+ * Serializable server command entry — sent over RPC (no handler).
+ */
+interface DevToolsServerCommandEntry extends DevToolsCommandBase {
+  source: 'server';
+  children?: DevToolsServerCommandEntry[];
+}
+/**
+ * Client command — registered in the webcomponent context.
+ */
+interface DevToolsClientCommand extends DevToolsCommandBase {
+  source: 'client';
+  /**
+   * Action for this command. Optional if the command only serves as a group for children.
+   * Return sub-commands for dynamic nested palette menus (runtime submenus).
+   */
+  action?: (...args: any[]) => void | DevToolsClientCommand[] | Promise<void | DevToolsClientCommand[]>;
+  /**
+   * Static sub-commands. Two levels max (parent → children).
+   */
+  children?: DevToolsClientCommand[];
+}
+/**
+ * Union of command entries visible in the palette.
+ */
+type DevToolsCommandEntry = DevToolsServerCommandEntry | DevToolsClientCommand;
+interface DevToolsCommandHandle {
+  readonly id: string;
+  update: (patch: Partial<Omit<DevToolsServerCommandInput, 'id'>>) => void;
+  unregister: () => void;
+}
+interface DevToolsCommandsHostEvents {
+  'command:registered': (command: DevToolsServerCommandEntry) => void;
+  'command:unregistered': (id: string) => void;
+}
+interface DevToolsCommandsHost {
+  readonly commands: Map<string, DevToolsServerCommandInput>;
+  readonly events: EventEmitter<DevToolsCommandsHostEvents>;
+  /**
+   * Register a command (with optional children).
+   */
+  register: (command: DevToolsServerCommandInput) => DevToolsCommandHandle;
+  /**
+   * Unregister a command by ID (removes parent and all children).
+   */
+  unregister: (id: string) => boolean;
+  /**
+   * Execute a command by ID. Searches top-level and children.
+   * Throws if not found or if command has no handler.
+   */
+  execute: (id: string, ...args: any[]) => Promise<unknown>;
+  /**
+   * Returns serializable list (no handlers), preserving tree structure.
+   */
+  list: () => DevToolsServerCommandEntry[];
+}
+interface DevToolsCommandShortcutOverrides {
+  /**
+   * Command ID → keybinding overrides. Empty array = shortcut disabled.
+   */
+  [commandId: string]: DevToolsCommandKeybinding[];
+}
+//#endregion
+//#region src/types/docks.d.ts
+interface DevToolsDockHost {
+  readonly views: Map<string, DevToolsDockUserEntry>;
+  readonly events: EventEmitter<{
+    'dock:entry:updated': (entry: DevToolsDockUserEntry) => void;
+  }>;
+  register: <T extends DevToolsDockUserEntry>(entry: T, force?: boolean) => {
+    update: (patch: Partial<T>) => void;
+  };
+  update: (entry: DevToolsDockUserEntry) => void;
+  values: (options?: {
+    includeBuiltin?: boolean;
+  }) => DevToolsDockEntry[];
+}
+type DevToolsDockEntryCategory = 'app' | 'framework' | 'web' | 'advanced' | 'default' | '~viteplus' | '~builtin';
+type DevToolsDockEntryIcon = string | {
+  light: string;
+  dark: string;
+};
+interface DevToolsDockEntryBase {
+  id: string;
+  title: string;
+  icon: DevToolsDockEntryIcon;
+  /**
+   * The default order of the entry in the dock.
+   * The higher the number the earlier it appears.
+   * @default 0
+   */
+  defaultOrder?: number;
+  /**
+   * The category of the entry
+   * @default 'default'
+   */
+  category?: DevToolsDockEntryCategory;
+  /**
+   * Conditional visibility expression.
+   * When set, the dock entry is only visible when the expression evaluates to true.
+   * Uses the same syntax as command `when` clauses.
+   *
+   * Set to `'false'` to unconditionally hide the entry.
+   *
+   * @example 'clientType == embedded'
+   * @see {@link import('../utils/when').evaluateWhen}
+   */
+  when?: string;
+  /**
+   * Badge text to display on the dock icon (e.g., unread count)
+   */
+  badge?: string;
+}
+interface ClientScriptEntry {
+  /**
+   * The filepath or module name to import from
+   */
+  importFrom: string;
+  /**
+   * The name to import the module as
+   *
+   * @default 'default'
+   */
+  importName?: string;
+}
+interface DevToolsViewIframe extends DevToolsDockEntryBase {
+  type: 'iframe';
+  url: string;
+  /**
+   * The id of the iframe, if multiple tabs is assigned with the same id, the iframe will be shared.
+   *
+   * When not provided, it would be treated as a unique frame.
+   */
+  frameId?: string;
+  /**
+   * Optional client script to import into the iframe
+   */
+  clientScript?: ClientScriptEntry;
+  /**
+   * Enable remote-UI mode: the core injects a connection descriptor
+   * (WS URL + pre-approved auth token) into the iframe URL so a hosted
+   * page can connect back via `connectRemoteDevTools()` from
+   * `@vitejs/devtools-kit/client` — without needing to ship a dist with
+   * the plugin.
+   *
+   * Requires dev mode (no effect in build mode — no WS server exists).
+   * When enabled, the dock is automatically hidden in build mode unless
+   * the author provides an explicit `when` clause.
+   *
+   * @example
+   *   remote: true
+   *   remote: { transport: 'query', originLock: false }
+   */
+  remote?: boolean | RemoteDockOptions;
+}
+interface RemoteDockOptions {
+  /**
+   * How to pass the connection descriptor to the hosted page.
+   *
+   * - `'fragment'` (default): appended as `#vite-devtools-kit-connection=...`.
+   *   Not sent in HTTP requests or Referer headers — safest for auth tokens.
+   * - `'query'`: appended as `?vite-devtools-kit-connection=...`. Use when
+   *   your hosting platform rewrites fragments or your SPA router repurposes
+   *   the fragment for navigation. The token will appear in server access
+   *   logs and outbound Referer headers.
+   *
+   * @default 'fragment'
+   */
+  transport?: 'fragment' | 'query';
+  /**
+   * Reject WS handshakes whose `Origin` header doesn't match the dock URL
+   * origin. Turn off when the same hosted app is served from multiple
+   * origins (e.g. preview deploys).
+   *
+   * @default true
+   */
+  originLock?: boolean;
+}
+type DevToolsViewLauncherStatus = 'idle' | 'loading' | 'success' | 'error';
+interface DevToolsViewLauncher extends DevToolsDockEntryBase {
+  type: 'launcher';
+  launcher: {
+    icon?: DevToolsDockEntryIcon;
+    title: string;
+    status?: DevToolsViewLauncherStatus;
+    error?: string;
+    description?: string;
+    buttonStart?: string;
+    buttonLoading?: string;
+    onLaunch: () => Promise<void>;
+  };
+}
+interface DevToolsViewAction extends DevToolsDockEntryBase {
+  type: 'action';
+  action: ClientScriptEntry;
+}
+interface DevToolsViewCustomRender extends DevToolsDockEntryBase {
+  type: 'custom-render';
+  renderer: ClientScriptEntry;
+}
+interface DevToolsViewBuiltin extends DevToolsDockEntryBase {
+  type: '~builtin';
+  id: '~terminals' | '~logs' | '~client-auth-notice' | '~settings' | '~popup';
+}
+interface JsonRenderElement {
+  type: string;
+  props?: Record<string, unknown>;
+  children?: string[];
+  /** json-render event bindings (e.g. `{ press: { action: "my:action" } }`) */
+  on?: Record<string, unknown>;
+  /** json-render visibility condition */
+  visible?: unknown;
+  /** json-render repeat binding */
+  repeat?: unknown;
+  /** Allow additional json-render element fields */
+  [key: string]: unknown;
+}
+interface JsonRenderSpec {
+  root: string;
+  elements: Record<string, JsonRenderElement>;
+  /** Initial client-side state model for $state/$bindState expressions */
+  state?: Record<string, unknown>;
+}
+interface JsonRenderer {
+  /** Replace the entire spec */
+  updateSpec: (spec: JsonRenderSpec) => void | Promise<void>;
+  /** Update json-render state values (shallow merge into spec.state) */
+  updateState: (state: Record<string, unknown>) => void | Promise<void>;
+  /** Internal: shared state key used by the client to subscribe */
+  readonly _stateKey: string;
+}
+interface DevToolsViewJsonRender extends DevToolsDockEntryBase {
+  type: 'json-render';
+  /** JsonRenderer handle created by ctx.createJsonRenderer() */
+  ui: JsonRenderer;
+}
+type DevToolsDockUserEntry = DevToolsViewIframe | DevToolsViewAction | DevToolsViewCustomRender | DevToolsViewLauncher | DevToolsViewJsonRender;
+type DevToolsDockEntry = DevToolsDockUserEntry | DevToolsViewBuiltin;
+type DevToolsDockEntriesGrouped = [category: string, entries: DevToolsDockEntry[]][];
+//#endregion
+//#region src/types/host.d.ts
+interface DevToolsHost {
+  /**
+   * Serve a static directory at the given URL base. Called by
+   * `DevToolsViewHost.hostStatic`. Implementations map this to whatever
+   * the underlying runtime expects (Vite middleware, h3 handler, no-op
+   * for build snapshots).
+   */
+  mountStatic: (base: string, distDir: string) => void | Promise<void>;
+  /**
+   * Return the public origin the host is reachable at, e.g.
+   * `http://localhost:5173`. Used by the dock host to enrich remote
+   * iframe URLs with a full `origin`. Called only when a dock needs an
+   * absolute URL; hosts that never serve remote docks can return any
+   * reasonable value.
+   */
+  resolveOrigin: () => string;
+}
+//#endregion
+//#region src/types/logs.d.ts
+type DevToolsLogLevel = 'info' | 'warn' | 'error' | 'success' | 'debug';
+type DevToolsLogEntryFrom = 'server' | 'browser';
+interface DevToolsLogElementPosition {
+  /** CSS selector for the element */
+  selector?: string;
+  /** Bounding box of the element */
+  boundingBox?: {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+  };
+  /** Human-readable description of the element */
+  description?: string;
+}
+interface DevToolsLogFilePosition {
+  /** Absolute or relative file path */
+  file: string;
+  /** Line number (1-based) */
+  line?: number;
+  /** Column number (1-based) */
+  column?: number;
+}
+interface DevToolsLogEntry {
+  /**
+   * Unique identifier for this log entry (auto-generated if not provided)
+   */
+  id: string;
+  /**
+   * Short title or summary of the log
+   */
+  message: string;
+  /**
+   * Optional detailed description or explanation
+   */
+  description?: string;
+  /**
+   * Severity level, determines color and icon
+   */
+  level: DevToolsLogLevel;
+  /**
+   * Optional stack trace string
+   */
+  stacktrace?: string;
+  /**
+   * Optional DOM element position info (e.g., for a11y issues)
+   */
+  elementPosition?: DevToolsLogElementPosition;
+  /**
+   * Optional source file position info (e.g., for lint errors)
+   */
+  filePosition?: DevToolsLogFilePosition;
+  /**
+   * Whether this log should also appear as a toast notification
+   */
+  notify?: boolean;
+  /**
+   * Origin of the log entry, automatically set by the context
+   */
+  from: DevToolsLogEntryFrom;
+  /**
+   * Grouping category (e.g., 'a11y', 'lint', 'runtime', 'test')
+   */
+  category?: string;
+  /**
+   * Optional tags/labels for filtering
+   */
+  labels?: string[];
+  /**
+   * Time in ms to auto-dismiss the toast notification (client-side)
+   */
+  autoDismiss?: number;
+  /**
+   * Time in ms to auto-delete this log entry (server-side)
+   */
+  autoDelete?: number;
+  /**
+   * Timestamp when the log was created (auto-generated if not provided)
+   */
+  timestamp: number;
+  /**
+   * Status of the log entry (e.g., 'loading' while an operation is in progress).
+   * Defaults to 'idle' when not specified.
+   */
+  status?: 'loading' | 'idle';
+}
+/**
+ * Input type for creating a log entry.
+ * `id`, `timestamp`, and `source` are auto-filled by the host.
+ */
+type DevToolsLogEntryInput = Omit<DevToolsLogEntry, 'id' | 'timestamp' | 'from'> & {
+  id?: string;
+  timestamp?: number;
+};
+interface DevToolsLogHandle {
+  /** The underlying log entry data */
+  readonly entry: DevToolsLogEntry;
+  /** Shortcut to entry.id */
+  readonly id: string;
+  /** Partial update of this log entry */
+  update: (patch: Partial<DevToolsLogEntryInput>) => Promise<DevToolsLogEntry | undefined>;
+  /** Remove this log entry */
+  dismiss: () => Promise<void>;
+}
+interface DevToolsLogsClient {
+  /**
+   * Add a log entry. Returns a Promise resolving to a handle for subsequent updates/dismissal.
+   * Can be used without `await` for fire-and-forget usage.
+   */
+  add: (input: DevToolsLogEntryInput) => Promise<DevToolsLogHandle>;
+  /** Remove a log entry by id */
+  remove: (id: string) => Promise<void>;
+  /** Clear all log entries */
+  clear: () => Promise<void>;
+}
+interface DevToolsLogsHost {
+  readonly entries: Map<string, DevToolsLogEntry>;
+  readonly events: EventEmitter<{
+    'log:added': (entry: DevToolsLogEntry) => void;
+    'log:updated': (entry: DevToolsLogEntry) => void;
+    'log:removed': (id: string) => void;
+    'log:cleared': () => void;
+  }>;
+  /**
+   * Add a new log entry. If an entry with the same `id` already exists, it will be updated instead.
+   * Returns a handle for subsequent updates/dismissal. Can be used without `await` for fire-and-forget.
+   */
+  add: (entry: DevToolsLogEntryInput) => Promise<DevToolsLogHandle>;
+  /**
+   * Update an existing log entry by id (partial update)
+   */
+  update: (id: string, patch: Partial<DevToolsLogEntryInput>) => Promise<DevToolsLogEntry | undefined>;
+  /**
+   * Remove a log entry by id
+   */
+  remove: (id: string) => Promise<void>;
+  /**
+   * Clear all log entries
+   */
+  clear: () => Promise<void>;
+}
+//#endregion
+//#region src/types/rpc-augments.d.ts
+/**
+ * To be extended
+ */
+interface DevToolsRpcClientFunctions {}
+/**
+ * To be extended
+ */
+interface DevToolsRpcServerFunctions {}
+/**
+ * To be extended
+ */
+interface DevToolsRpcSharedStates {}
+//#endregion
+//#region src/types/settings.d.ts
+interface DevToolsDocksUserSettings {
+  docksHidden: string[];
+  docksCategoriesHidden: string[];
+  docksPinned: string[];
+  docksCustomOrder: Record<string, number>;
+  showIframeAddressBar: boolean;
+  closeOnOutsideClick: boolean;
+  commandShortcuts: DevToolsCommandShortcutOverrides;
+}
+//#endregion
+//#region src/types/terminals.d.ts
+interface DevToolsTerminalSessionStreamChunkEvent {
+  id: string;
+  chunks: string[];
+  ts: number;
+}
+interface DevToolsTerminalHost {
+  readonly sessions: Map<string, DevToolsTerminalSession>;
+  readonly events: EventEmitter<{
+    'terminal:session:updated': (session: DevToolsTerminalSession) => void;
+    'terminal:session:stream-chunk': (data: DevToolsTerminalSessionStreamChunkEvent) => void;
+  }>;
+  register: (session: DevToolsTerminalSession) => DevToolsTerminalSession;
+  update: (session: DevToolsTerminalSession) => void;
+  startChildProcess: (executeOptions: DevToolsChildProcessExecuteOptions, terminal: Omit<DevToolsTerminalSessionBase, 'status'>) => Promise<DevToolsChildProcessTerminalSession>;
+}
+type DevToolsTerminalStatus = 'running' | 'stopped' | 'error';
+interface DevToolsTerminalSessionBase {
+  id: string;
+  title: string;
+  description?: string;
+  status: DevToolsTerminalStatus;
+  icon?: DevToolsDockEntryIcon;
+}
+interface DevToolsTerminalSession extends DevToolsTerminalSessionBase {
+  buffer?: string[];
+  stream?: ReadableStream<string>;
+}
+interface DevToolsChildProcessExecuteOptions {
+  command: string;
+  args: string[];
+  cwd?: string;
+  env?: Record<string, string>;
+}
+interface DevToolsChildProcessTerminalSession extends DevToolsTerminalSession {
+  type: 'child-process';
+  executeOptions: DevToolsChildProcessExecuteOptions;
+  getChildProcess: () => ChildProcess | undefined;
+  terminate: () => Promise<void>;
+  restart: () => Promise<void>;
+}
+//#endregion
+//#region src/types/utils.d.ts
+type Thenable<T> = T | Promise<T>;
+type EntriesToObject<T extends readonly [string, any][]> = { [K in T[number] as K[0]]: K[1] };
+type PartialWithoutId<T extends {
+  id: string;
+}> = Partial<Omit<T, 'id'>> & {
+  id: string;
+};
+//#endregion
+//#region src/types/views.d.ts
+interface DevToolsViewHost {
+  /**
+   * @internal
+   */
+  buildStaticDirs: {
+    baseUrl: string;
+    distDir: string;
+  }[];
+  /**
+   * Helper to host static files
+   * - In `dev` mode, it will register middleware to `viteServer.middlewares` to host the static files
+   * - In `build` mode, it will copy the static files to the dist directory
+   */
+  hostStatic: (baseUrl: string, distDir: string) => void;
+}
+//#endregion
+//#region ../../../node_modules/.pnpm/immer@11.1.4/node_modules/immer/dist/immer.d.ts
+interface Patch {
+  op: "replace" | "remove" | "add";
+  path: (string | number)[];
+  value?: any;
+}
+type Objectish = AnyObject | AnyArray | AnyMap | AnySet;
+type AnyObject = {
+  [key: string]: any;
+};
+type AnyArray = Array<any>;
+type AnySet = Set<any>;
+type AnyMap = Map<any, any>;
+/** Returns true if the given value is an Immer draft */
+//#endregion
+//#region src/utils/shared-state.d.ts
+type ImmutablePrimitive = undefined | null | boolean | string | number | Function;
+type Immutable<T> = T extends ImmutablePrimitive ? T : T extends Array<infer U> ? ImmutableArray<U> : T extends Map<infer K, infer V> ? ImmutableMap<K, V> : T extends Set<infer M> ? ImmutableSet<M> : ImmutableObject<T>;
+type ImmutableArray<T> = ReadonlyArray<Immutable<T>>;
+type ImmutableMap<K, V> = ReadonlyMap<Immutable<K>, Immutable<V>>;
+type ImmutableSet<T> = ReadonlySet<Immutable<T>>;
+type ImmutableObject<T> = { readonly [K in keyof T]: Immutable<T[K]> };
+/**
+ * State host that is immutable by default with explicit mutate.
+ */
+interface SharedState<T> {
+  /**
+   * Get the current state. Immutable.
+   */
+  value: () => Immutable<T>;
+  /**
+   * Subscribe to state changes.
+   */
+  on: EventEmitter<SharedStateEvents<T>>['on'];
+  /**
+   * Mutate the state.
+   */
+  mutate: (fn: (state: T) => void, syncId?: string) => void;
+  /**
+   * Apply patches to the state.
+   */
+  patch: (patches: Patch[], syncId?: string) => void;
+  /**
+   * Sync IDs that have been applied to the state.
+   */
+  syncIds: Set<string>;
+}
+interface SharedStateEvents<T> {
+  updated: (fullState: T, patches: Patch[] | undefined, syncId: string) => void;
+}
+interface SharedStateOptions<T> {
+  /**
+   * Initial state.
+   */
+  initialValue: T;
+  /**
+   * Enable patches.
+   *
+   * @default false
+   */
+  enablePatches?: boolean;
+}
+declare function createSharedState<T extends Objectish>(options: SharedStateOptions<T>): SharedState<T>;
+//#endregion
+//#region src/types/rpc.d.ts
+interface DevToolsNodeRpcSession {
+  meta: DevToolsNodeRpcSessionMeta;
+  rpc: BirpcReturn<DevToolsRpcClientFunctions, DevToolsRpcServerFunctions, false>;
+}
+interface RpcBroadcastOptions<METHOD, Args extends any[]> {
+  method: METHOD;
+  args: Args;
+  optional?: boolean;
+  event?: boolean;
+  filter?: (client: BirpcReturn<DevToolsRpcClientFunctions, DevToolsRpcServerFunctions, false>) => boolean | void;
+}
+type RpcFunctionsHost = RpcFunctionsCollectorBase<DevToolsRpcServerFunctions, DevToolsNodeContext> & {
+  /**
+   * Invoke a locally registered server RPC function directly.
+   *
+   * This bypasses transport and is useful for server-side cross-function calls.
+   */
+  invokeLocal: <T extends keyof DevToolsRpcServerFunctions, Args extends Parameters<DevToolsRpcServerFunctions[T]>>(method: T, ...args: Args) => Promise<Awaited<ReturnType<DevToolsRpcServerFunctions[T]>>>;
+  /**
+   * Broadcast a message to all connected clients
+   */
+  broadcast: <T extends keyof DevToolsRpcClientFunctions, Args extends Parameters<DevToolsRpcClientFunctions[T]>>(options: RpcBroadcastOptions<T, Args>) => Promise<void>;
+  /**
+   * Get the current RPC client
+   *
+   * Available in RPC functions to get the current RPC client
+   */
+  getCurrentRpcSession: () => DevToolsNodeRpcSession | undefined;
+  /**
+   * The shared state host
+   */
+  sharedState: RpcSharedStateHost;
+};
+interface RpcSharedStateGetOptions<T> {
+  sharedState?: SharedState<T>;
+  initialValue?: T;
+}
+interface RpcSharedStateHost {
+  get: <T extends keyof DevToolsRpcSharedStates>(key: T, options?: RpcSharedStateGetOptions<DevToolsRpcSharedStates[T]>) => Promise<SharedState<DevToolsRpcSharedStates[T]>>;
+  keys: () => string[];
+  /**
+   * Subscribe to new shared-state keys becoming available. Fires when
+   * `get(key, ...)` creates a fresh entry (not on subsequent gets).
+   * Useful for protocol adapters (e.g. MCP) that surface shared state
+   * as dynamic resources.
+   */
+  onKeyAdded: (fn: (key: string) => void) => () => void;
+}
+//#endregion
+//#region src/types/context.d.ts
+interface DevToolsCapabilities {
+  rpc?: boolean;
+  views?: boolean;
+}
+interface DevToolsNodeContext {
+  readonly workspaceRoot: string;
+  readonly cwd: string;
+  readonly mode: 'dev' | 'build';
+  /**
+   * Host runtime abstraction — exposes `mountStatic` / `resolveOrigin`.
+   */
+  host: DevToolsHost;
+  rpc: RpcFunctionsHost;
+  docks: DevToolsDockHost;
+  views: DevToolsViewHost;
+  utils: DevToolsNodeUtils;
+  terminals: DevToolsTerminalHost;
+  logs: DevToolsLogsHost;
+  commands: DevToolsCommandsHost;
+  /**
+   * Agent host — aggregates the agent-exposed surface of this devtool.
+   *
+   * @experimental
+   */
+  agent: DevToolsAgentHost;
+  /**
+   * Create a JsonRenderer handle for building json-render powered UIs.
+   */
+  createJsonRenderer: (spec: JsonRenderSpec) => JsonRenderer;
+}
+interface DevToolsNodeUtils {
+  /**
+   * Create a simple client script from a function or stringified code.
+   *
+   * @deprecated testing helper; prefer a proper importable module.
+   * @experimental
+   */
+  createSimpleClientScript: (fn: string | ((ctx: any) => void)) => ClientScriptEntry;
+}
+interface ConnectionMeta {
+  backend: 'websocket' | 'static';
+  websocket?: number | string;
+}
+interface RemoteConnectionInfo extends ConnectionMeta {
+  backend: 'websocket';
+  websocket: string;
+  v: 1;
+  authToken: string;
+  origin: string;
+}
+//#endregion
+//#region src/types/devtool.d.ts
+type DevtoolRuntime = 'cli' | 'build' | 'spa' | 'vite' | 'kit' | 'embedded';
+/**
+ * Classification of how a devtool is being deployed. Hosted adapters
+ * (`vite`, `kit`, `embedded`) share their origin with a host app and
+ * must namespace their mount path under `/.<id>/`. Standalone adapters
+ * (`cli`, `spa`, `build`) own the origin and default to `/`.
+ */
+type DevtoolDeploymentKind = 'standalone' | 'hosted';
+interface DevtoolCliOptions {
+  /** Binary name; default: the devtool's `id`. */
+  command?: string;
+  /** Preferred port for the dev server (default 9999). */
+  port?: number;
+  /** Port scan range, forwarded to `get-port-please`. */
+  portRange?: [number, number];
+  /** Prefer a random open port. */
+  random?: boolean;
+  /** Default host to bind to; `--host` overrides. */
+  host?: string;
+  /**
+   * Auto-open the browser when the dev server starts.
+   * `true` opens the resolved origin; a string opens that relative path.
+   * The `--open` / `--no-open` flags override this.
+   */
+  open?: boolean | string;
+  /**
+   * Skip the RPC trust handshake. Set to `false` for trusted
+   * single-user localhost tools. Default `true`.
+   *
+   * Forwarded to `startHttpAndWs` as a no-op placeholder until devframe
+   * ships its own auth layer; `@vitejs/devtools` honors the equivalent
+   * `devtools.clientAuth` today.
+   */
+  auth?: boolean;
+  /** Author's SPA dist directory (served as the devtool's UI). */
+  distDir?: string;
+  /**
+   * Capability-side CAC hook. Called with the CAC instance after the
+   * adapter registers its built-in commands (`build` / `spa` / `mcp`)
+   * but before `createCli`'s own `configureCli` caller. Use this to
+   * contribute tool-specific flags and subcommands from the definition
+   * itself.
+   */
+  configure?: (cli: CAC) => void;
+  /**
+   * Typed CLI flags for the default `dev` command, backed by valibot
+   * schemas. The adapter registers matching `--kebab-key` options on
+   * CAC, validates the parsed values, and forwards the typed bag to
+   * `setup(ctx, { flags })`.
+   *
+   * Use {@link defineCliFlags} to preserve the literal schema-map
+   * shape, and {@link InferCliFlags} to recover the typed output at the
+   * call site:
+   *
+   * ```ts
+   * const appFlags = defineCliFlags({
+   *   depth: v.pipe(v.number(), v.integer()),
+   *   config: v.optional(v.string()),
+   * })
+   *
+   * defineDevtool({
+   *   cli: { flags: appFlags },
+   *   setup(ctx, info) {
+   *     const flags = info.flags as InferCliFlags<typeof appFlags>
+   *   },
+   * })
+   * ```
+   */
+  flags?: CliFlagsSchema;
+}
+interface DevtoolSpaOptions {
+  base?: string;
+  /**
+   * How the deployed SPA loads its data.
+   * - `'query'` — read from URL search params.
+   * - `'upload'` — accept a file drag-drop.
+   * - `'none'`  — use the baked RPC dump only.
+   */
+  loader?: 'query' | 'upload' | 'none';
+}
+interface DevtoolBrowserContext {
+  /**
+   * The connected RPC client (may be write-disabled in static/spa modes).
+   */
+  rpc: unknown;
+}
+/**
+ * Runtime information threaded into `setup(ctx, info)`. Adapters
+ * populate the fields that make sense for their deployment. In
+ * particular, `createCli` fills `flags` with the parsed CAC bag.
+ */
+interface DevtoolSetupInfo {
+  /** Parsed CLI flags, populated by the CLI adapter. */
+  flags?: Record<string, unknown>;
+}
+interface DevtoolDefinition {
+  id: string;
+  name: string;
+  icon?: string | {
+    light: string;
+    dark: string;
+  };
+  version?: string;
+  /**
+   * Mount path override. Defaults depend on the adapter:
+   * `/` for standalone (`cli` / `spa` / `build`), `/.<id>/` for hosted
+   * (`vite` / `kit` / `embedded`).
+   */
+  basePath?: string;
+  capabilities?: {
+    dev?: boolean | Record<string, boolean>;
+    build?: boolean | Record<string, boolean>;
+    spa?: boolean | Record<string, boolean>;
+  };
+  /** Server-side setup — the primary entrypoint. Runs in every runtime. */
+  setup: (ctx: DevToolsNodeContext, info?: DevtoolSetupInfo) => void | Promise<void>;
+  /** Browser-only setup for the SPA adapter (bundled into the client). */
+  setupBrowser?: (ctx: DevtoolBrowserContext) => void | Promise<void>;
+  cli?: DevtoolCliOptions;
+  spa?: DevtoolSpaOptions;
+}
+declare function defineDevtool(d: DevtoolDefinition): DevtoolDefinition;
+//#endregion
+export { DevToolsLogsHost as $, DevToolsViewHost as A, AgentHandle as At, DevToolsTerminalStatus as B, EventUnsubscribe as Bt, ImmutableSet as C, DevToolsCommandHandle as Ct, createSharedState as D, DevToolsCommandsHostEvents as Dt, SharedStateOptions as E, DevToolsCommandsHost as Et, DevToolsChildProcessTerminalSession as F, AgentTool as Ft, DevToolsLogElementPosition as G, DevToolsRpcClientFunctions as H, CliFlagsSchema as Ht, DevToolsTerminalHost as I, AgentToolInput as It, DevToolsLogEntryInput as J, DevToolsLogEntry as K, DevToolsTerminalSession as L, DevToolsAgentHost as Lt, PartialWithoutId as M, AgentResource as Mt, Thenable as N, AgentResourceContent as Nt, Objectish as O, DevToolsServerCommandEntry as Ot, DevToolsChildProcessExecuteOptions as P, AgentResourceInput as Pt, DevToolsLogsClient as Q, DevToolsTerminalSessionBase as R, DevToolsAgentHostEvents as Rt, ImmutableObject as S, DevToolsCommandEntry as St, SharedStateEvents as T, DevToolsCommandShortcutOverrides as Tt, DevToolsRpcServerFunctions as U, InferCliFlags as Ut, DevToolsDocksUserSettings as V, EventsMap as Vt, DevToolsRpcSharedStates as W, defineCliFlags as Wt, DevToolsLogHandle as X, DevToolsLogFilePosition as Y, DevToolsLogLevel as Z, RpcSharedStateGetOptions as _, JsonRenderSpec as _t, DevtoolRuntime as a, DevToolsDockEntryCategory as at, ImmutableArray as b, DevToolsClientCommand as bt, defineDevtool as c, DevToolsDockUserEntry as ct, DevToolsNodeContext as d, DevToolsViewCustomRender as dt, DevToolsHost as et, DevToolsNodeUtils as f, DevToolsViewIframe as ft, RpcFunctionsHost as g, JsonRenderElement as gt, RpcBroadcastOptions as h, DevToolsViewLauncherStatus as ht, DevtoolDeploymentKind as i, DevToolsDockEntryBase as it, EntriesToObject as j, AgentManifest as jt, Patch as k, DevToolsServerCommandInput as kt, ConnectionMeta as l, DevToolsViewAction as lt, DevToolsNodeRpcSession as m, DevToolsViewLauncher as mt, DevtoolCliOptions as n, DevToolsDockEntriesGrouped as nt, DevtoolSetupInfo as o, DevToolsDockEntryIcon as ot, RemoteConnectionInfo as p, DevToolsViewJsonRender as pt, DevToolsLogEntryFrom as q, DevtoolDefinition as r, DevToolsDockEntry as rt, DevtoolSpaOptions as s, DevToolsDockHost as st, DevtoolBrowserContext as t, ClientScriptEntry as tt, DevToolsCapabilities as u, DevToolsViewBuiltin as ut, RpcSharedStateHost as v, JsonRenderer as vt, SharedState as w, DevToolsCommandKeybinding as wt, ImmutableMap as x, DevToolsCommandBase as xt, Immutable as y, RemoteDockOptions as yt, DevToolsTerminalSessionStreamChunkEvent as z, EventEmitter as zt };