@svadmin/devtools 0.2.1

package/README.md

@@ -0,0 +1,39 @@
+# @svadmin/devtools
+
+Headless diagnostics core for svadmin.
+
+`@svadmin/devtools-contract` defines the JSON-safe snapshot, event, and
+diagnostic vocabulary. This package adds the runtime pieces that adapters, SSR,
+and the CLI can share:
+
+- `createDevtoolsCollector()` — a bounded, redacting in-memory collector with
+  `recordEvent`, `recordDiagnostic`, `snapshot`, `subscribe`, and `clear`.
+- `buildProviderDiagnostics(bundle)` — provider configuration/capability matrix.
+- `buildResourceDiagnostics(resources)` / `buildRouteDiagnostics(resources)` —
+  resource operations, menu visibility, provider routing, and route paths.
+- `toPermissionDiagnostic(resource, action, result)` — normalizes access-control
+  results for display.
+- Re-exports the whole `@svadmin/devtools-contract` surface.
+
+UI rendering stays in `@svadmin/ui` (`DevTools.svelte`); this package is the
+headless boundary so non-UI consumers do not depend on `devframe` or Svelte.
+
+## Usage
+
+```ts
+import { createDevtoolsCollector, buildProviderDiagnostics } from '@svadmin/devtools';
+
+const collector = createDevtoolsCollector({ source: 'frontend', maxEvents: 200 });
+
+collector.recordDiagnostic({
+  code: 'provider.missing',
+  source: 'frontend',
+  severity: 'warning',
+  message: 'liveProvider is not configured',
+});
+
+const snapshot = collector.snapshot({ requestId: 'req-1' });
+const providers = buildProviderDiagnostics(config.providers);
+```
+
+Secrets are redacted by `redactDevtoolsRecord` before a snapshot is produced.

package/dist/index.d.ts

@@ -0,0 +1,63 @@
+/**
+ * @svadmin/devtools — headless diagnostics core.
+ *
+ * Folds the `@svadmin/devtools-contract` snapshot/event/diagnostic vocabulary
+ * into a small runtime collector plus pure diagnostic builders. UI rendering
+ * stays in `@svadmin/ui`; this package is what adapters, SSR, and the CLI can
+ * use to publish redacted, JSON-safe diagnostics.
+ */
+export { createDevtoolsSnapshot, redactDevtoolsRecord } from '@svadmin/devtools-contract';
+export type { DevtoolsCacheDiagnostics, DevtoolsDiagnostic, DevtoolsEvent, DevtoolsLocation, DevtoolsProviderDiagnostic, DevtoolsQueryDiagnostic, DevtoolsSeverity, DevtoolsSnapshot, DevtoolsSource, DevtoolsTraceContext, SvadminDevtoolsSnapshot, } from '@svadmin/devtools-contract';
+import { type DevtoolsDiagnostic, type DevtoolsEvent, type DevtoolsProviderDiagnostic, type DevtoolsSnapshot, type DevtoolsSource, type DevtoolsTraceContext } from '@svadmin/devtools-contract';
+import type { ProviderBundle, ResourceDefinition } from '@svadmin/core';
+export interface DevtoolsCollectorOptions {
+    source?: DevtoolsSource;
+    maxEvents?: number;
+    maxDiagnostics?: number;
+    context?: DevtoolsTraceContext;
+}
+export interface DevtoolsCollector {
+    readonly source: DevtoolsSource;
+    recordEvent(event: DevtoolsEvent): void;
+    recordDiagnostic(diagnostic: DevtoolsDiagnostic): void;
+    clear(): void;
+    snapshot(context?: DevtoolsTraceContext): DevtoolsSnapshot;
+    subscribe(listener: (snapshot: DevtoolsSnapshot) => void): () => void;
+}
+/**
+ * Bounded in-memory collector. Events and diagnostics are capped so a long-lived
+ * admin session cannot grow without limit; snapshots are redacted on build.
+ */
+export declare function createDevtoolsCollector(options?: DevtoolsCollectorOptions): DevtoolsCollector;
+/** Builds provider diagnostics from a composed ProviderBundle. */
+export declare function buildProviderDiagnostics(bundle: ProviderBundle): DevtoolsProviderDiagnostic[];
+export interface DevtoolsResourceOperations {
+    list: boolean;
+    create: boolean;
+    edit: boolean;
+    delete: boolean;
+    show: boolean;
+}
+export interface DevtoolsResourceDiagnostic {
+    name: string;
+    label: string;
+    showInMenu: boolean;
+    operations: DevtoolsResourceOperations;
+    dataProvider?: string;
+}
+export declare function buildResourceDiagnostics(resources: readonly ResourceDefinition[]): DevtoolsResourceDiagnostic[];
+export interface DevtoolsRouteDiagnostic {
+    resource: string;
+    path: string;
+}
+export declare function buildRouteDiagnostics(resources: readonly ResourceDefinition[], basePath?: string): DevtoolsRouteDiagnostic[];
+export interface DevtoolsPermissionDiagnostic {
+    resource: string;
+    action: string;
+    allowed: boolean;
+    reason?: string;
+}
+export declare function toPermissionDiagnostic(resource: string, action: string, result: {
+    can: boolean;
+    reason?: string;
+}): DevtoolsPermissionDiagnostic;

package/dist/index.js

@@ -0,0 +1,128 @@
+/**
+ * @svadmin/devtools — headless diagnostics core.
+ *
+ * Folds the `@svadmin/devtools-contract` snapshot/event/diagnostic vocabulary
+ * into a small runtime collector plus pure diagnostic builders. UI rendering
+ * stays in `@svadmin/ui`; this package is what adapters, SSR, and the CLI can
+ * use to publish redacted, JSON-safe diagnostics.
+ */
+export { createDevtoolsSnapshot, redactDevtoolsRecord } from '@svadmin/devtools-contract';
+import { createDevtoolsSnapshot, } from '@svadmin/devtools-contract';
+function mergeContext(base, extra) {
+    const requestId = extra.requestId ?? base.requestId;
+    const traceId = extra.traceId ?? base.traceId;
+    const correlationId = extra.correlationId ?? base.correlationId;
+    return {
+        ...(requestId !== undefined ? { requestId } : {}),
+        ...(traceId !== undefined ? { traceId } : {}),
+        ...(correlationId !== undefined ? { correlationId } : {}),
+    };
+}
+/**
+ * Bounded in-memory collector. Events and diagnostics are capped so a long-lived
+ * admin session cannot grow without limit; snapshots are redacted on build.
+ */
+export function createDevtoolsCollector(options = {}) {
+    const source = options.source ?? 'frontend';
+    const maxEvents = options.maxEvents ?? 500;
+    const maxDiagnostics = options.maxDiagnostics ?? 200;
+    const baseContext = options.context ?? {};
+    let events = [];
+    let diagnostics = [];
+    const listeners = new Set();
+    function build(context = {}) {
+        const merged = mergeContext(baseContext, context);
+        return createDevtoolsSnapshot({
+            source,
+            diagnostics,
+            events,
+            ...(merged.requestId !== undefined ? { requestId: merged.requestId } : {}),
+            ...(merged.traceId !== undefined ? { traceId: merged.traceId } : {}),
+            ...(merged.correlationId !== undefined ? { correlationId: merged.correlationId } : {}),
+        });
+    }
+    function notify() {
+        const snapshot = build();
+        for (const listener of listeners)
+            listener(snapshot);
+    }
+    return {
+        source,
+        recordEvent(event) {
+            events = [...events, event].slice(-maxEvents);
+            notify();
+        },
+        recordDiagnostic(diagnostic) {
+            diagnostics = [...diagnostics, diagnostic].slice(-maxDiagnostics);
+            notify();
+        },
+        clear() {
+            events = [];
+            diagnostics = [];
+            notify();
+        },
+        snapshot(context) {
+            return build(context);
+        },
+        subscribe(listener) {
+            listeners.add(listener);
+            if (events.length > 0 || diagnostics.length > 0)
+                listener(build());
+            return () => listeners.delete(listener);
+        },
+    };
+}
+const PROVIDER_CAPABILITIES = [
+    ['dataProvider', 'data'],
+    ['authProvider', 'auth'],
+    ['accessControlProvider', 'access-control'],
+    ['liveProvider', 'live'],
+    ['auditLogProvider', 'audit-log'],
+    ['notificationProvider', 'notification'],
+    ['chatProvider', 'ai'],
+    ['agentProvider', 'ai'],
+    ['taskProvider', 'task'],
+    ['routerProvider', 'router'],
+    ['tenantAdapter', 'tenant'],
+    ['organizationProvider', 'organization'],
+    ['identityGovernanceProvider', 'identity-governance'],
+    ['sessionProvider', 'session'],
+    ['credentialProvider', 'credentials'],
+];
+/** Builds provider diagnostics from a composed ProviderBundle. */
+export function buildProviderDiagnostics(bundle) {
+    return PROVIDER_CAPABILITIES.map(([key, capability]) => ({
+        name: key,
+        configured: bundle[key] !== undefined && bundle[key] !== null,
+        capabilities: capability,
+    }));
+}
+export function buildResourceDiagnostics(resources) {
+    return resources.map((resource) => ({
+        name: resource.name,
+        label: resource.label,
+        showInMenu: resource.showInMenu ?? true,
+        operations: {
+            list: true,
+            create: resource.canCreate ?? true,
+            edit: resource.canEdit ?? true,
+            delete: resource.canDelete ?? true,
+            show: resource.canShow ?? true,
+        },
+        ...(resource.provider?.dataProviderName !== undefined
+            ? { dataProvider: resource.provider.dataProviderName }
+            : {}),
+    }));
+}
+export function buildRouteDiagnostics(resources, basePath = '') {
+    const prefix = basePath.replace(/\/+$/u, '');
+    return resources.map((resource) => ({ resource: resource.name, path: `${prefix}/${resource.name}` }));
+}
+export function toPermissionDiagnostic(resource, action, result) {
+    return {
+        resource,
+        action,
+        allowed: result.can,
+        ...(result.reason !== undefined ? { reason: result.reason } : {}),
+    };
+}

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "@svadmin/devtools",
+  "version": "0.2.1",
+  "type": "module",
+  "description": "Headless diagnostics core for svadmin — query traces, provider diagnostics, permission/resource/route inspection",
+  "license": "MIT",
+  "keywords": [
+    "svadmin",
+    "devtools",
+    "diagnostics",
+    "observability",
+    "admin"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/vibeunion/svadmin.git",
+    "directory": "packages/devtools"
+  },
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "svadmin": {
+    "capabilities": [
+      "devtools-traces",
+      "provider-diagnostics",
+      "resource-diagnostics"
+    ],
+    "core": "^0.55.0",
+    "stability": "experimental",
+    "migration": null
+  },
+  "dependencies": {
+    "@svadmin/devtools-contract": "^0.2.0"
+  },
+  "peerDependencies": {
+    "@svadmin/core": "^0.58.0"
+  },
+  "peerDependenciesMeta": {
+    "@svadmin/core": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "typescript": "^7.0.2"
+  },
+  "scripts": {
+    "build": "bun ../../scripts/build-node-package.ts"
+  }
+}