feat(data-inspector): example source inspects the environment, opt-out only

The built-in example source is now always registered unless explicitly
opted out (option exampleSource: false; CLI --no-example; agent env
DEVFRAME_DATA_INSPECTOR_EXAMPLE=0) — the agent and file-serving CLI no
longer suppress it automatically. Beyond the playground branch it now
answers real questions: the devframe context (registered RPC functions,
services, storage dirs), OS info, and live process stats via query-time
getters, with matching suggested queries.

Author: antfubot

docs/plugins/data-inspector.md

@@ -16,7 +16,7 @@ Package: `@devframes/plugin-data-inspector` · framework: **Vue + Vite**
 - **Filters** — exclude functions, `_`-prefixed, or `$`-prefixed properties from results and skeleton alike.
 - **Saved queries** — recipes (`query` + optional title/description + the filters they were authored with), id-keyed, in two scopes: **workspace** (committable, shared with the team) and **project** (per-checkout).
 
-A built-in example source demonstrates all of it on first run; disable it with `createDataInspectorDevframe({ exampleSource: false })` once your own sources are registered.
+A built-in **example source** is always registered alongside your own: it exposes the devframe context (registered RPC functions, services, storage dirs), OS info, and live process stats — with query-time getters that change on every re-run — plus a small playground branch exercising every viewer capability. Opt out with `createDataInspectorDevframe({ exampleSource: false })` (CLI: `--no-example`, agent: `DEVFRAME_DATA_INSPECTOR_EXAMPLE=0`).
 
 ## Providing data sources
 

plugins/data-inspector/src/agent/index.ts

@@ -62,6 +62,13 @@ export interface ExposeDataInspectorOptions {
   discoveryFile?: boolean
   /** Suppress the stderr banner. */
   silent?: boolean
+  /**
+   * Register the built-in example source (devframe context, OS, live
+   * process stats of the target). Default `true`; set `false` (or
+   * `DEVFRAME_DATA_INSPECTOR_EXAMPLE=0` on the `--import` path) to expose
+   * only the target's own registrations.
+   */
+  exampleSource?: boolean
 }
 
 export interface DataInspectorAgent {
@@ -94,9 +101,7 @@ export async function exposeDataInspector(options: ExposeDataInspectorOptions =
   }
 
   const context: DevframeNodeContext = await createHostContext({ cwd, mode: 'dev', host })
-  // Attach exists to inspect the target's own objects; the example source
-  // would only be noise next to them.
-  setupDataInspector(context, { exampleSource: false })
+  setupDataInspector(context, { exampleSource: options.exampleSource })
 
   const useAuth = options.auth ?? true
   const token = useAuth ? (options.token ?? randomToken()) : undefined
@@ -148,6 +153,7 @@ if (process.env.DEVFRAME_DATA_INSPECTOR === '1' || process.env.DEVFRAME_DATA_INS
     port: process.env.DEVFRAME_DATA_INSPECTOR_PORT ? Number(process.env.DEVFRAME_DATA_INSPECTOR_PORT) : undefined,
     auth: process.env.DEVFRAME_DATA_INSPECTOR_AUTH !== '0',
     token: process.env.DEVFRAME_DATA_INSPECTOR_TOKEN,
+    exampleSource: process.env.DEVFRAME_DATA_INSPECTOR_EXAMPLE !== '0',
   }).catch((error) => {
     console.error('[data-inspector] agent failed to start:', error)
   })

plugins/data-inspector/src/cli.ts

@@ -51,12 +51,11 @@ export function createDataInspectorCli() {
     .option('--host <host>', 'Host to bind to', { default: 'localhost' })
     .option('--open', 'Open the browser on start')
     .option('--no-open', 'Do not open the browser')
-    .action(async (files: string[], flags: { port?: number, host: string, open?: boolean }) => {
+    .option('--no-example', 'Skip the built-in example source')
+    .action(async (files: string[], flags: { port?: number, host: string, open?: boolean, example?: boolean }) => {
       for (const file of files)
         registerDataSource(createFileDataSource(file))
-      // With files given, they are the point; the example source only backs
-      // the empty first-run.
-      const def = createDataInspectorDevframe({ exampleSource: files.length === 0 })
+      const def = createDataInspectorDevframe({ exampleSource: flags.example })
       await createDevServer(def, {
         host: flags.host,
         port: flags.port ? Number(flags.port) : undefined,

plugins/data-inspector/src/node/example-source.ts

@@ -1,4 +1,6 @@
+import type { DevframeNodeContext } from 'devframe/types'
 import type { DataSourceEntry } from '../registry/index'
+import os from 'node:os'
 import process from 'node:process'
 
 /** Id of the built-in example source (namespaced like every source id). */
@@ -14,22 +16,17 @@ class RequestLog {
   ])
 }
 
-function createExampleData(): Record<string, unknown> {
-  const log = new RequestLog()
+/** A small synthetic branch exercising every viewer capability. */
+function createPlayground(): Record<string, unknown> {
   const node: Record<string, unknown> = { name: 'root' }
   node.self = node // circular structures render as $ref markers
-
-  const data: Record<string, unknown> = {
-    server: {
-      name: 'example',
-      port: 5173,
-      tags: new Set(['dev', 'local', 'example']),
-      middlewares: [
-        { name: 'compression', handler: () => {} },
-        { name: 'static', handler: () => {} },
-      ],
-    },
-    requests: log,
+  return {
+    requests: new RequestLog(),
+    tags: new Set(['dev', 'local', 'example']),
+    middlewares: [
+      { name: 'compression', handler: () => {} },
+      { name: 'static', handler: () => {} },
+    ],
     build: {
       hash: 'c3f7c4e',
       size: 1024n * 512n,
@@ -40,9 +37,51 @@ function createExampleData(): Record<string, unknown> {
       })),
     },
     tree: node,
-    process: { pid: process.pid, node: process.version, platform: process.platform },
   }
-  // An own getter: reads at query time, so re-running shows the data is live.
+}
+
+/** The devframe context, projected to its inspectable surface. */
+function describeContext(ctx: DevframeNodeContext): Record<string, unknown> {
+  return {
+    cwd: ctx.cwd,
+    workspaceRoot: ctx.workspaceRoot,
+    mode: ctx.mode,
+    rpcFunctions: Array.from(ctx.rpc.definitions.keys()).sort(),
+    services: ctx.services.keys().sort(),
+    storage: {
+      workspace: ctx.host.getStorageDir('workspace'),
+      project: ctx.host.getStorageDir('project'),
+      global: ctx.host.getStorageDir('global'),
+    },
+  }
+}
+
+function createExampleData(ctx?: DevframeNodeContext): Record<string, unknown> {
+  const data: Record<string, unknown> = {
+    ...(ctx ? { devframe: describeContext(ctx) } : {}),
+    os: {
+      platform: os.platform(),
+      arch: os.arch(),
+      release: os.release(),
+      hostname: os.hostname(),
+      cpus: { count: os.cpus().length, model: os.cpus()[0]?.model },
+      memory: { totalMb: Math.round(os.totalmem() / 1024 / 1024), freeMb: Math.round(os.freemem() / 1024 / 1024) },
+      homedir: os.homedir(),
+      uptimeHours: Math.round(os.uptime() / 36) / 100,
+    },
+    process: {
+      pid: process.pid,
+      execPath: process.execPath,
+      argv: process.argv,
+      versions: process.versions,
+    },
+    playground: createPlayground(),
+  }
+  // Own getters read at query time, so re-running shows the data is live.
+  Object.defineProperties(data.process as object, {
+    memory: { enumerable: true, get: () => process.memoryUsage() },
+    uptimeSeconds: { enumerable: true, get: () => Math.round(process.uptime()) },
+  })
   Object.defineProperty(data, 'queriedAt', {
     enumerable: true,
     get: () => new Date().toISOString(),
@@ -51,36 +90,47 @@ function createExampleData(): Record<string, unknown> {
 }
 
 /**
- * The built-in example source — a small live graph exercising everything the
- * viewer can show (Maps, Sets, class instances, circulars, BigInt, functions,
- * a query-time getter), with suggested queries as starting points. Sources
- * registered by your plugins and hosts appear next to it; disable it via
- * `createDataInspectorDevframe({ exampleSource: false })`.
+ * The built-in example source — always registered unless opted out
+ * (`exampleSource: false`). Lets the viewer query simple environment info
+ * (the devframe context: registered RPC functions, services, storage dirs;
+ * OS and live process stats) plus a small playground branch exercising
+ * everything the viewer can show (Maps, Sets, class instances, circulars,
+ * BigInt, functions, query-time getters).
  */
-export function createExampleDataSource(): DataSourceEntry {
+export function createExampleDataSource(ctx?: DevframeNodeContext): DataSourceEntry {
   let data: Record<string, unknown> | undefined
   return {
     id: EXAMPLE_SOURCE_ID,
     title: 'Example data',
-    description: 'A built-in playground graph. Register your own sources to inspect real objects.',
+    description: 'Devframe context, OS and process info, plus a playground graph.',
     icon: 'i-ph:flask-duotone',
-    data: () => data ??= createExampleData(),
+    data: () => data ??= createExampleData(ctx),
     queries: [
+      ...(ctx
+        ? [{
+            title: 'Registered RPC functions',
+            description: 'Everything callable on this devframe connection',
+            query: 'devframe.rpcFunctions',
+          }]
+        : []),
+      {
+        title: 'OS at a glance',
+        query: 'os.({ platform, arch, cpus, memory })',
+      },
+      {
+        title: 'Live process memory',
+        description: 'Query-time getter: re-run and watch it change',
+        query: '{ memory: process.memory, uptime: process.uptimeSeconds, at: queriedAt }',
+      },
       {
         title: 'Busiest endpoints',
         description: 'Live Map entries, sorted',
-        query: 'requests.entries.mapEntries().value.sort(hits desc)',
+        query: 'playground.requests.entries.mapEntries().value.sort(hits desc)',
       },
       {
         title: 'Large modules as a table',
         description: 'Filter and project an array',
-        query: 'build.modules.[sizeKb > 80].({ id, sizeKb })',
-      },
-      {
-        title: 'Server config (data only)',
-        description: 'Filters strip the middleware functions',
-        query: 'server',
-        excludeFunctions: true,
+        query: 'playground.build.modules.[sizeKb > 80].({ id, sizeKb })',
       },
       { title: 'Everything', query: '' },
     ],

plugins/data-inspector/src/node/index.ts

@@ -28,8 +28,10 @@ export function setupDataInspector(ctx: DevframeNodeContext, options: SetupDataI
   if (!ctx.services.has(DATA_SOURCES_SERVICE_ID))
     ctx.services.provide(DATA_SOURCES_SERVICE_ID, createDataSourcesService())
 
+  // Always on unless opted out: the example source doubles as an
+  // environment inspector (this context, OS, live process stats).
   if ((options.exampleSource ?? true) && !getDataSource(EXAMPLE_SOURCE_ID))
-    registerDataSource(createExampleDataSource())
+    registerDataSource(createExampleDataSource(ctx))
 
   onDataSourcesChanged(() => {
     ctx.rpc.broadcast(SOURCES_CHANGED_EVENT as never)

plugins/data-inspector/test/registry.test.ts

@@ -107,4 +107,34 @@ describe('example source', () => {
       expect(out.ok, `suggested query "${recipe.title}" must run`).toBe(true)
     }
   })
+
+  it('exposes os and live process info', async () => {
+    const { createExampleDataSource } = await import('../src/node/example-source')
+    const entry = createExampleDataSource()
+    const data = await resolveSourceData(entry) as Record<string, any>
+    expect(data.os.platform).toBeTypeOf('string')
+    expect(data.os.cpus.count).toBeGreaterThan(0)
+    expect(data.process.memory.heapUsed).toBeGreaterThan(0)
+    expect(data.process.versions.node).toBeTypeOf('string')
+  })
+
+  it('describes the devframe context when given one', async () => {
+    const { createExampleDataSource } = await import('../src/node/example-source')
+    const ctx = {
+      cwd: '/w/app',
+      workspaceRoot: '/w',
+      mode: 'dev',
+      rpc: { definitions: new Map([['a:fn', {}]]) },
+      services: { keys: () => ['a:svc'] },
+      host: { getStorageDir: (scope: string) => `/w/${scope}` },
+    } as any
+    const data = await resolveSourceData(createExampleDataSource(ctx)) as Record<string, any>
+    expect(data.devframe).toMatchObject({
+      cwd: '/w/app',
+      mode: 'dev',
+      rpcFunctions: ['a:fn'],
+      services: ['a:svc'],
+      storage: { workspace: '/w/workspace', project: '/w/project', global: '/w/global' },
+    })
+  })
 })

tests/__snapshots__/tsnapi/@devframes/plugin-data-inspector/agent.snapshot.d.ts

@@ -19,6 +19,7 @@ export interface ExposeDataInspectorOptions {
   token?: string;
   discoveryFile?: boolean;
   silent?: boolean;
+  exampleSource?: boolean;
 }
 // #endregion
 

tests/__snapshots__/tsnapi/@devframes/plugin-data-inspector/node.snapshot.d.ts

@@ -8,7 +8,7 @@ export interface SetupDataInspectorOptions {
 // #endregion
 
 // #region Functions
-export declare function createExampleDataSource(): DataSourceEntry;
+export declare function createExampleDataSource(_?: DevframeNodeContext): DataSourceEntry;
 export declare function setupDataInspector(_: DevframeNodeContext, _?: SetupDataInspectorOptions): void;
 // #endregion