@vibeunion/devtools-protocol 0.1.0

package/README.md

@@ -0,0 +1,10 @@
+# @vibeunion/devtools-protocol
+
+Shared JSON-safe contracts for frontend and SupaCloud DevTools adapters.
+
+The package contains no transport, database, logging, or UI dependency. It
+defines trace/correlation metadata, diagnostics, events, snapshots, and
+recursive redaction for credentials and signed URLs. It also defines the
+complete local cache mutation vocabulary, including query and mutation cache
+operations, plus the svadmin snapshot/provider/query diagnostic shapes so a
+single contract serves frontend, svadmin, and SupaCloud adapters.

package/dist/index.d.ts

@@ -0,0 +1,116 @@
+export type DevtoolsSource = 'frontend' | 'supacloud' | 'compiler';
+export type DevtoolsSeverity = 'info' | 'warning' | 'error';
+export type DevtoolsTraceContext = {
+    requestId?: string;
+    traceId?: string;
+    correlationId?: string;
+};
+export type DevtoolsLocation = {
+    file?: string;
+    line?: number;
+    column?: number;
+};
+export type DevtoolsDiagnostic = DevtoolsTraceContext & {
+    code: string;
+    source: DevtoolsSource;
+    severity: DevtoolsSeverity;
+    message: string;
+    location?: DevtoolsLocation;
+    fix?: {
+        kind: string;
+        safe: boolean;
+        input?: Record<string, unknown>;
+    };
+};
+export type DevtoolsEvent = (DevtoolsTraceContext & {
+    type: 'request.started' | 'request.finished' | 'request.failed';
+    durationMs?: number;
+}) | (DevtoolsTraceContext & {
+    type: 'query.started' | 'query.finished' | 'query.failed';
+    provider: string;
+    resource?: string;
+    operation: string;
+}) | (DevtoolsTraceContext & {
+    type: 'task.updated';
+    taskId: string;
+    status: string;
+}) | {
+    type: 'diagnostic.emitted';
+    diagnostic: DevtoolsDiagnostic;
+};
+export type DevtoolsSnapshot = DevtoolsTraceContext & {
+    version: 1;
+    source: DevtoolsSource;
+    diagnostics: DevtoolsDiagnostic[];
+    events: DevtoolsEvent[];
+};
+export type DevtoolsCacheSelector = {
+    provider?: string;
+    resource?: string;
+    operation?: string;
+    queryHash?: string;
+    mutationKey?: string;
+};
+export type DevtoolsCacheMutation = 'cancel' | 'invalidate' | 'refetch' | 'remove' | 'reset' | 'clear' | 'clearMutations' | 'cancelMutations' | 'removeMutations' | 'resetMutations';
+export type DevtoolsCacheCapabilities = {
+    query: DevtoolsCacheMutation[];
+    mutation: DevtoolsCacheMutation[];
+};
+export type DevtoolsCacheActionRequest = {
+    action: DevtoolsCacheMutation;
+    selector?: DevtoolsCacheSelector;
+    confirmation?: string;
+};
+export type DevtoolsCacheActionResult = {
+    action: DevtoolsCacheMutation;
+    matched: number;
+    changed: number;
+};
+export type DevtoolsCacheDiagnostics = {
+    queries: {
+        total: number;
+        fetching: number;
+        stale: number;
+        errors: number;
+    };
+    mutations: {
+        total: number;
+        pending: number;
+        paused: number;
+        errors: number;
+    };
+};
+export type DevtoolsProviderDiagnostic = {
+    name: string;
+    configured: boolean;
+    capabilities: string;
+};
+export type DevtoolsQueryDiagnostic = {
+    provider: string;
+    resource: string;
+    operation: string;
+    status: string;
+    retries: number;
+    duration: string;
+    cacheAge: string;
+    invalidation: string;
+};
+/**
+ * Svadmin-specific devtools snapshot shape. It extends the shared versioned
+ * snapshot vocabulary while staying JSON-safe and dependency-free so the same
+ * contract can be consumed by frontend adapters and SupaCloud tooling.
+ */
+export type SvadminDevtoolsSnapshot = {
+    version: 1;
+    environment: 'development';
+    route: string;
+    locale: string;
+    theme: string;
+    colorTheme: string;
+    resourceCount: number;
+    providers: DevtoolsProviderDiagnostic[];
+    cache: DevtoolsCacheDiagnostics;
+    queries: DevtoolsQueryDiagnostic[];
+};
+export declare function redactDevtoolsRecord(value: unknown): unknown;
+export declare function createDevtoolsSnapshot(input: Omit<DevtoolsSnapshot, 'version'>): DevtoolsSnapshot;

package/dist/index.js

@@ -0,0 +1,20 @@
+// src/index.ts
+var SECRET_KEY = /token|secret|password|credential|authorization|cookie|signed.?url|service.?role|api.?key|private.?key|jwt/i;
+function redactDevtoolsRecord(value) {
+  if (Array.isArray(value))
+    return value.map(redactDevtoolsRecord);
+  if (value && typeof value === "object") {
+    return Object.fromEntries(Object.entries(value).map(([key, entry]) => [
+      key,
+      SECRET_KEY.test(key) ? "[redacted]" : redactDevtoolsRecord(entry)
+    ]));
+  }
+  return value;
+}
+function createDevtoolsSnapshot(input) {
+  return redactDevtoolsRecord({ version: 1, ...input });
+}
+export {
+  createDevtoolsSnapshot,
+  redactDevtoolsRecord
+};

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "@vibeunion/devtools-protocol",
+  "version": "0.1.0",
+  "description": "Shared JSON-safe DevTools protocol for frontend and SupaCloud adapters",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": ["dist", "README.md"],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "clean": "rm -rf dist",
+    "build": "bun run clean && bun build src/index.ts --outdir dist --target node && tsc -b tsconfig.json --force",
+    "test": "bun test"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+ssh://git@github.com/vibeunion/devtools.git",
+    "directory": "packages/protocol"
+  }
+}