refactor(devframe): centralize diagnostics reporter in devframe/utils/nostics

Move the ANSI console reporter registration into the shared
`devframe/utils/nostics` `defineDiagnostics` wrapper, which pre-wires it
ahead of any caller-supplied reporters. Every module-level
`diagnostics.ts` (devframe core, @devframes/hub, @devframes/json-render,
and the built-in plugins) now just calls `defineDiagnostics({ docsBase,
codes })` — no local reporter, no `colors`/`ansiFormatter` imports.

Delete the per-package `diagnostics-reporter.ts` files and collapse the
host's `defineDiagnostics` to the shared wrapper (it already prepends the
reporter, so no extra merging is needed).

Author: antfubot

AGENTS.md

@@ -91,7 +91,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. Import `defineDiagnostics`, `Diagnostic`, and `ansiFormatter` from `devframe/utils/nostics` rather than from `nostics` directly - it re-exports the package's API so plugins don't need their own `nostics` dependency.
+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.
 

packages/devframe/src/node/diagnostics.ts

@@ -1,12 +1,10 @@
 import { defineDiagnostics } from 'devframe/utils/nostics'
-import { devframeReporter } from '../utils/diagnostics-reporter'
 
 // 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 'devframe/utils/nostics'
-import { devframeReporter } from '../utils/diagnostics-reporter'
 
 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 'devframe/utils/nostics'
-import { devframeReporter } from '../utils/diagnostics-reporter'
 
 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 'devframe/utils/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 'devfra
 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
 }

packages/devframe/src/utils/diagnostics-reporter.ts

@@ -1,14 +1,55 @@
+import type { AnyDiagnosticReporter, Diagnostic, DiagnosticDefinition, Diagnostics } from 'nostics'
+import { colors } from 'devframe/utils/colors'
+import { defineDiagnostics as defineNosticsDiagnostics } from 'nostics'
+import { ansiFormatter } from 'nostics/formatters/ansi'
+
+const formatAnsi = ansiFormatter(colors)
+
+/**
+ * The reporter every {@link defineDiagnostics} call below wires in ahead of
+ * any caller-supplied ones: prints the diagnostic through devframe's own
+ * ANSI colors via `console[method]` (default `'warn'`).
+ */
+function devframeReporter(d: Diagnostic, { method = 'warn' }: { method?: 'log' | 'warn' | 'error' } = {}): void {
+  // eslint-disable-next-line no-console
+  console[method](formatAnsi(d))
+}
+
 /**
- * Re-exports `nostics`'s public API — `defineDiagnostics`, the `Diagnostic`
- * class, its supporting types, and the ANSI formatter — so integrations that
- * define their own coded `diagnostics.ts` (the built-in plugins,
- * `@devframes/hub`, `@devframes/json-render`, …) reach it through
- * `devframe/utils/nostics` instead of taking a direct dependency on
- * `nostics` themselves.
+ * Options accepted by {@link defineDiagnostics} — identical to `nostics`'s
+ * own `DefineDiagnosticsOptions`, minus the reporter devframe already
+ * prepends.
  */
+export type DevframeDefineDiagnosticsOptions<
+  Codes extends Record<string, DiagnosticDefinition>,
+  Reporters extends readonly AnyDiagnosticReporter[] = [],
+> = Parameters<typeof defineDiagnostics<Codes, Reporters>>[0]
+
+/**
+ * Drop-in replacement for `nostics`'s `defineDiagnostics()` with devframe's
+ * ANSI console reporter pre-wired ahead of any `reporters` passed in. Every
+ * `diagnostics.ts` in devframe core, `@devframes/hub`, `@devframes/json-render`,
+ * and the built-in plugins defines its codes through this instead of
+ * `nostics`'s own `defineDiagnostics` — the reporter registration lives
+ * here, once, so none of them need to build their own reporter (`colors`,
+ * `ansiFormatter`) or take a direct dependency on `nostics` themselves.
+ */
+export function defineDiagnostics<
+  const Codes extends Record<string, DiagnosticDefinition>,
+  const Reporters extends readonly AnyDiagnosticReporter[] = [],
+>(options: {
+  docsBase?: string | ((code: keyof Codes) => string | undefined)
+  codes: Codes
+  reporters?: Reporters
+}): Diagnostics<Codes, readonly [typeof devframeReporter, ...Reporters]> {
+  return defineNosticsDiagnostics({
+    ...options,
+    reporters: [devframeReporter, ...(options.reporters ?? [])],
+  }) as Diagnostics<Codes, readonly [typeof devframeReporter, ...Reporters]>
+}
+
 export {
   createConsoleReporter,
-  defineDiagnostics,
   defineProdDiagnostics,
   Diagnostic,
   formatDiagnostic,
@@ -18,7 +59,6 @@ export type {
   AnyDiagnosticReporter,
   ConsoleMethod,
   ConsoleReporterOptions,
-  DefineDiagnosticsOptions,
   DiagnosticCallParams,
   DiagnosticDefinition,
   DiagnosticHandle,

packages/devframe/src/utils/nostics.ts

@@ -1,5 +1,4 @@
 import { defineDiagnostics } from 'devframe/utils/nostics'
-import { hubReporter } from '../utils/diagnostics-reporter'
 
 // Hub-side diagnostics for docks, terminals, messages, and commands.
 // Shares the `DF` prefix with devframe core; the hub reserves the
@@ -12,7 +11,6 @@ import { hubReporter } from '../utils/diagnostics-reporter'
 //   DF8400-DF8499 — commands
 export const diagnostics = defineDiagnostics({
   docsBase: 'https://devfra.me/errors',
-  reporters: [hubReporter],
   codes: {
     DF8000: {
       why: (p: { id: string }) => `Devframe id "${p.id}" collides with a reserved hub path — it cannot be mounted directly under the hub base.`,

packages/hub/src/node/diagnostics.ts

@@ -1,23 +1,11 @@
-import type { Diagnostic } from 'devframe/utils/nostics'
-import { colors as c } from 'devframe/utils/colors'
-import { ansiFormatter, defineDiagnostics } from 'devframe/utils/nostics'
-
-const formatAnsi = ansiFormatter(c)
-
-interface ReporterOptions { method?: 'log' | 'warn' | 'error' }
-
-function jsonRenderReporter(d: Diagnostic, { method = 'warn' }: ReporterOptions = {}): void {
-  // eslint-disable-next-line no-console
-  console[method](formatAnsi(d))
-}
+import { defineDiagnostics } from 'devframe/utils/nostics'
 
 // `@devframes/json-render` protocol/runtime diagnostics. These share the
 // `DF` prefix and live in the devframe core range (next free after the
 // current highest `DF00xx`, DF0037). Browser-only render failures keep
 // `console.*` in the UI package.
 export const diagnostics = defineDiagnostics({
   docsBase: 'https://devfra.me/errors',
-  reporters: [jsonRenderReporter],
   codes: {
     DF0038: {
       why: (p: { id: string, key: string, issues: string }) =>