feat(devframe): re-export nostics via devframe/utils/nostics (#243)

Author: antfubot

AGENTS.md

@@ -92,7 +92,7 @@ Any change to one lands in the other in the same PR: adding a dock, wiring a new
 
 ## Structured Diagnostics (Error Codes)
 
-All node-side warnings and errors use structured diagnostics via [`nostics`](https://www.npmjs.com/package/nostics). Never use raw `console.warn`, `console.error`, or `throw new Error` with ad-hoc messages in node-side code - always define a coded diagnostic.
+All node-side warnings and errors use structured diagnostics via [`nostics`](https://www.npmjs.com/package/nostics). Never use raw `console.warn`, `console.error`, or `throw new Error` with ad-hoc messages in node-side code - always define a coded diagnostic. Import `defineDiagnostics` (and `Diagnostic` for `instanceof` checks) from `devframe/utils/nostics` rather than from `nostics` directly - it pre-wires devframe's ANSI console reporter, so a plugin's `diagnostics.ts` never builds its own reporter (`colors`, `ansiFormatter`) or depends on `nostics` itself.
 
 Prefix: **`DF`**. Codes are sequential 4-digit numbers (e.g. `DF0033`). Check the existing diagnostics file to find the next available number.
 

alias.ts

@@ -29,6 +29,7 @@ export const alias = {
   'devframe/utils/hash': r('devframe/src/utils/hash.ts'),
   'devframe/utils/launch-editor': r('devframe/src/utils/launch-editor.ts'),
   'devframe/utils/nanoid': r('devframe/src/utils/nanoid.ts'),
+  'devframe/utils/nostics': r('devframe/src/utils/nostics.ts'),
   'devframe/utils/open': r('devframe/src/utils/open.ts'),
   'devframe/utils/remote-assets': r('devframe/src/utils/remote-assets.ts'),
   'devframe/utils/simple-schema': r('devframe/src/utils/simple-schema.ts'),

packages/devframe/package.json

@@ -51,6 +51,7 @@
     "./utils/hash": "./dist/utils/hash.mjs",
     "./utils/launch-editor": "./dist/utils/launch-editor.mjs",
     "./utils/nanoid": "./dist/utils/nanoid.mjs",
+    "./utils/nostics": "./dist/utils/nostics.mjs",
     "./utils/open": "./dist/utils/open.mjs",
     "./utils/remote-assets": "./dist/utils/remote-assets.mjs",
     "./utils/simple-schema": "./dist/utils/simple-schema.mjs",

packages/devframe/src/adapters/mcp/__tests__/stringify.test.ts

@@ -1,4 +1,4 @@
-import { Diagnostic } from 'nostics'
+import { Diagnostic } from 'devframe/utils/nostics'
 import { describe, expect, it } from 'vitest'
 import { formatMcpError, stringifyForMcp } from '../stringify'
 

packages/devframe/src/adapters/mcp/stringify.ts

@@ -1,4 +1,4 @@
-import { Diagnostic } from 'nostics'
+import { Diagnostic } from 'devframe/utils/nostics'
 
 /**
  * JSON-coercing serializer for MCP text payloads.

packages/devframe/src/cli/connect.ts

@@ -2,7 +2,7 @@ import type { Tool } from '@modelcontextprotocol/server'
 import type { DevframeInstanceRecord } from '../node/instance-registry'
 import process from 'node:process'
 import { toAgentToolName } from 'devframe/utils/agent-tool-name'
-import { Diagnostic } from 'nostics'
+import { Diagnostic } from 'devframe/utils/nostics'
 import { joinURL } from 'ufo'
 import { diagnostics } from '../node/diagnostics'
 import { listLiveDevframeInstances, probeDevframeOrigin } from '../node/instance-registry'

packages/devframe/src/node/diagnostics.ts

@@ -1,12 +1,10 @@
-import { defineDiagnostics } from 'nostics'
-import { devframeReporter } from '../utils/diagnostics-reporter'
+import { defineDiagnostics } from 'devframe/utils/nostics'
 
 // DF00xx codes are allocated across packages (e.g. @devframes/json-render
 // owns DF0037–DF0041), so this file alone doesn't show the next free
 // number — check `docs/errors/` for the full allocation before adding one.
 export const diagnostics = defineDiagnostics({
   docsBase: 'https://devfra.me/errors',
-  reporters: [devframeReporter],
   codes: {
     DF0006: {
       why: (p: { name: string }) => `RPC function "${p.name}" is not registered`,

packages/devframe/src/node/host-diagnostics.ts

@@ -1,6 +1,5 @@
 import type { DevframeDiagnosticsHost as DevframeDiagnosticsHostType, DevframeDiagnosticsLogger, DevframeNodeContext } from 'devframe/types'
-import { defineDiagnostics } from 'nostics'
-import { devframeReporter } from '../utils/diagnostics-reporter'
+import { defineDiagnostics } from 'devframe/utils/nostics'
 
 export class DevframeDiagnosticsHost implements DevframeDiagnosticsHostType {
   private _registry: Record<string, unknown> = {}
@@ -9,16 +8,9 @@ export class DevframeDiagnosticsHost implements DevframeDiagnosticsHostType {
     get: (_, code: string) => this._registry[code],
   })
 
-  readonly defineDiagnostics: DevframeDiagnosticsHostType['defineDiagnostics'] = (opts) => {
-    const merged = {
-      ...opts,
-      reporters: [devframeReporter, ...(opts.reporters ?? [])],
-    } as Parameters<typeof defineDiagnostics>[0]
-    // Runtime passthrough: the per-call `Codes` generic can't be threaded
-    // through this assigned arrow, so the narrow return type is restored by
-    // the property's declared signature at every call site.
-    return defineDiagnostics(merged) as any
-  }
+  // Already pre-wires devframe's ANSI console reporter — no extra merging
+  // needed here, the host's `defineDiagnostics` just is the shared one.
+  readonly defineDiagnostics: DevframeDiagnosticsHostType['defineDiagnostics'] = defineDiagnostics
 
   constructor(
     public readonly context: DevframeNodeContext,

packages/devframe/src/rpc/diagnostics.ts

@@ -1,9 +1,7 @@
-import { defineDiagnostics } from 'nostics'
-import { devframeReporter } from '../utils/diagnostics-reporter'
+import { defineDiagnostics } from 'devframe/utils/nostics'
 
 export const diagnostics = defineDiagnostics({
   docsBase: 'https://devfra.me/errors',
-  reporters: [devframeReporter],
   codes: {
     DF0019: {
       why: (p: { name: string }) =>

packages/devframe/src/types/diagnostics.ts

@@ -1,4 +1,4 @@
-import type { defineDiagnostics, Diagnostic, DiagnosticDefinition } from 'nostics'
+import type { defineDiagnostics } from 'devframe/utils/nostics'
 
 /**
  * The shared diagnostics lookup exposed by the host. A `Proxy` that resolves
@@ -10,15 +10,14 @@ import type { defineDiagnostics, Diagnostic, DiagnosticDefinition } from 'nostic
 export type DevframeDiagnosticsLogger = Record<string, any>
 
 /**
- * Options accepted by the host's `defineDiagnostics()` factory — mirrors
- * `nostics`'s shape but the host pre-wires its ANSI console reporter, so
- * plugins typically omit `reporters`.
+ * Options accepted by the host's `defineDiagnostics()` factory. Re-exported
+ * from `devframe/utils/nostics` — the same shape every module-level
+ * `diagnostics.ts` (devframe core, `@devframes/hub`, the built-in plugins)
+ * accepts, since `host.defineDiagnostics()` and the top-level
+ * `defineDiagnostics` from `devframe/utils/nostics` pre-wire the identical
+ * ANSI console reporter.
  */
-export interface DevframeDefineDiagnosticsOptions<Codes extends Record<string, DiagnosticDefinition>> {
-  docsBase?: string | ((code: keyof Codes) => string | undefined)
-  codes: Codes
-  reporters?: ReadonlyArray<(d: Diagnostic, o?: any) => void>
-}
+export type { DevframeDefineDiagnosticsOptions } from 'devframe/utils/nostics'
 
 /**
  * Host for structured diagnostics — a thin layer over `nostics` that lets
@@ -64,10 +63,9 @@ export interface DevframeDiagnosticsHost {
 
   /**
    * Build a typed diagnostics object with the host's ANSI console reporter
-   * pre-wired. Mirrors `nostics`'s `defineDiagnostics` so integrations don't
-   * need to take a direct dependency on `nostics`.
+   * pre-wired. The same `devframe/utils/nostics` `defineDiagnostics` every
+   * built-in plugin's module-level `diagnostics.ts` uses, so integrations
+   * don't need to take a direct dependency on `nostics`.
    */
-  defineDiagnostics: <const Codes extends Record<string, DiagnosticDefinition>>(
-    options: DevframeDefineDiagnosticsOptions<Codes>,
-  ) => ReturnType<typeof defineDiagnostics<Codes, any>>
+  defineDiagnostics: typeof defineDiagnostics
 }