@svadmin/devtools 0.4.4 → 0.6.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/index.d.ts +56 -1
- package/dist/index.js +176 -0
- package/package.json +2 -2
package/dist/index.d.ts
CHANGED
|
@@ -8,7 +8,7 @@
|
|
|
8
8
|
*/
|
|
9
9
|
export { createDevtoolsSnapshot, redactDevtoolsRecord } from '@svadmin/devtools-contract';
|
|
10
10
|
export type { DevtoolsCacheDiagnostics, DevtoolsDiagnostic, DevtoolsEvent, DevtoolsLocation, DevtoolsProviderDiagnostic, DevtoolsQueryDiagnostic, DevtoolsSeverity, DevtoolsSnapshot, DevtoolsSource, DevtoolsTraceContext, SvadminDevtoolsSnapshot, } from '@svadmin/devtools-contract';
|
|
11
|
-
import { type DevtoolsDiagnostic, type DevtoolsEvent, type DevtoolsProviderDiagnostic, type DevtoolsSnapshot, type DevtoolsSource, type DevtoolsTraceContext } from '@svadmin/devtools-contract';
|
|
11
|
+
import { type DevtoolsDiagnostic, type DevtoolsEvent, type DevtoolsLocation, type DevtoolsProviderDiagnostic, type DevtoolsSnapshot, type DevtoolsSource, type DevtoolsTraceContext } from '@svadmin/devtools-contract';
|
|
12
12
|
import type { ProviderBundle, ResourceDefinition } from '@svadmin/core';
|
|
13
13
|
export type DevtoolsHealthStatus = 'healthy' | 'warning' | 'error';
|
|
14
14
|
export interface DevtoolsHealthSummary {
|
|
@@ -101,3 +101,58 @@ export declare function buildDevtoolsHealthSummary(input: {
|
|
|
101
101
|
* copied into the result.
|
|
102
102
|
*/
|
|
103
103
|
export declare function buildAdminDiagnostics(options: BuildAdminDiagnosticsOptions): DevtoolsAppDiagnostics;
|
|
104
|
+
export interface SelfHealingIssue {
|
|
105
|
+
category: 'PERMISSION_DENIED' | 'SCHEMA_MISMATCH' | 'NETWORK_ERROR' | 'RUNTIME_EXCEPTION';
|
|
106
|
+
code: string;
|
|
107
|
+
message: string;
|
|
108
|
+
resource?: string;
|
|
109
|
+
operation?: string;
|
|
110
|
+
suggestedAction: string;
|
|
111
|
+
location?: DevtoolsLocation;
|
|
112
|
+
}
|
|
113
|
+
export interface SelfHealingReport {
|
|
114
|
+
hasErrors: boolean;
|
|
115
|
+
errorCount: number;
|
|
116
|
+
issues: SelfHealingIssue[];
|
|
117
|
+
agentPrompt: string;
|
|
118
|
+
}
|
|
119
|
+
export interface CaptureRuntimeErrorOptions {
|
|
120
|
+
source?: DevtoolsSource;
|
|
121
|
+
resource?: string;
|
|
122
|
+
operation?: string;
|
|
123
|
+
traceId?: string;
|
|
124
|
+
requestId?: string;
|
|
125
|
+
correlationId?: string;
|
|
126
|
+
location?: DevtoolsLocation;
|
|
127
|
+
}
|
|
128
|
+
/**
|
|
129
|
+
* Normalizes any runtime exception or API failure into a structured DevtoolsDiagnostic
|
|
130
|
+
* with machine-actionable category and remediation guidance.
|
|
131
|
+
*/
|
|
132
|
+
export declare function captureRuntimeError(error: unknown, context?: CaptureRuntimeErrorOptions): DevtoolsDiagnostic;
|
|
133
|
+
/**
|
|
134
|
+
* Builds an AI-ready self-healing report from captured diagnostics, formatting
|
|
135
|
+
* the failure root-causes and providing a direct prompt for AI Agent remediation.
|
|
136
|
+
*/
|
|
137
|
+
export declare function buildSelfHealingReport(diagnostics: readonly DevtoolsDiagnostic[], _events?: readonly DevtoolsEvent[]): SelfHealingReport;
|
|
138
|
+
export type ResourcePatchAction = 'updateField' | 'toggleColumnVisibility' | 'updateColumnTitle' | 'updatePageSize' | 'reorderColumns';
|
|
139
|
+
export interface ResourcePatch {
|
|
140
|
+
resource: string;
|
|
141
|
+
action: ResourcePatchAction;
|
|
142
|
+
field?: string;
|
|
143
|
+
column?: string;
|
|
144
|
+
value: unknown;
|
|
145
|
+
targetComponent?: string;
|
|
146
|
+
}
|
|
147
|
+
export interface ResourcePatchResult {
|
|
148
|
+
success: boolean;
|
|
149
|
+
patch: ResourcePatch;
|
|
150
|
+
summary: string;
|
|
151
|
+
suggestedPatchCode: string;
|
|
152
|
+
agentPrompt: string;
|
|
153
|
+
}
|
|
154
|
+
/**
|
|
155
|
+
* Builds a structured writeback patch from visual inspector interactions,
|
|
156
|
+
* generating actionable code snippets and an Agent-executable prompt.
|
|
157
|
+
*/
|
|
158
|
+
export declare function buildResourcePatch(patch: ResourcePatch): ResourcePatchResult;
|
package/dist/index.js
CHANGED
|
@@ -175,3 +175,179 @@ export function buildAdminDiagnostics(options) {
|
|
|
175
175
|
health: buildDevtoolsHealthSummary({ diagnostics, providers, resources, routes }),
|
|
176
176
|
};
|
|
177
177
|
}
|
|
178
|
+
/**
|
|
179
|
+
* Normalizes any runtime exception or API failure into a structured DevtoolsDiagnostic
|
|
180
|
+
* with machine-actionable category and remediation guidance.
|
|
181
|
+
*/
|
|
182
|
+
export function captureRuntimeError(error, context = {}) {
|
|
183
|
+
let message = 'Unknown runtime error';
|
|
184
|
+
let code = 'runtime.error';
|
|
185
|
+
let category = 'RUNTIME_EXCEPTION';
|
|
186
|
+
let suggestedAction = 'Inspect component logic and error stack trace.';
|
|
187
|
+
if (error instanceof Error) {
|
|
188
|
+
message = error.message;
|
|
189
|
+
if (/403|forbidden|permission|unauthorized|access denied/i.test(message)) {
|
|
190
|
+
code = 'auth.forbidden';
|
|
191
|
+
category = 'PERMISSION_DENIED';
|
|
192
|
+
suggestedAction = context.resource
|
|
193
|
+
? `Grant permission for operation '${context.operation ?? 'read'}' on resource '${context.resource}' in AccessControlProvider or AuthProvider`
|
|
194
|
+
: 'Verify user credentials, active permissions, or AccessControlProvider rules';
|
|
195
|
+
}
|
|
196
|
+
else if (/404|not found/i.test(message)) {
|
|
197
|
+
code = 'resource.not_found';
|
|
198
|
+
category = 'NETWORK_ERROR';
|
|
199
|
+
suggestedAction = context.resource
|
|
200
|
+
? `Verify record ID and endpoint URL for resource '${context.resource}' in DataProvider`
|
|
201
|
+
: 'Verify endpoint URL and routing configuration';
|
|
202
|
+
}
|
|
203
|
+
else if (/schema|invalid|type|validation|must be/i.test(message)) {
|
|
204
|
+
code = 'schema.mismatch';
|
|
205
|
+
category = 'SCHEMA_MISMATCH';
|
|
206
|
+
suggestedAction = context.resource
|
|
207
|
+
? `Check field definitions and type validation rules for resource '${context.resource}' in ResourceDefinition`
|
|
208
|
+
: 'Ensure payload data matches expected schema definition';
|
|
209
|
+
}
|
|
210
|
+
else if (/network|failed to fetch|econnrefused|timeout/i.test(message)) {
|
|
211
|
+
code = 'network.failure';
|
|
212
|
+
category = 'NETWORK_ERROR';
|
|
213
|
+
suggestedAction = 'Check backend server health, CORS headers, and network connectivity';
|
|
214
|
+
}
|
|
215
|
+
}
|
|
216
|
+
else if (typeof error === 'string') {
|
|
217
|
+
message = error;
|
|
218
|
+
}
|
|
219
|
+
else if (error && typeof error === 'object' && 'message' in error) {
|
|
220
|
+
message = String(error.message);
|
|
221
|
+
}
|
|
222
|
+
return {
|
|
223
|
+
code,
|
|
224
|
+
source: context.source ?? 'frontend',
|
|
225
|
+
severity: 'error',
|
|
226
|
+
message,
|
|
227
|
+
...(context.traceId !== undefined ? { traceId: context.traceId } : {}),
|
|
228
|
+
...(context.requestId !== undefined ? { requestId: context.requestId } : {}),
|
|
229
|
+
...(context.correlationId !== undefined ? { correlationId: context.correlationId } : {}),
|
|
230
|
+
...(context.location !== undefined ? { location: context.location } : {}),
|
|
231
|
+
fix: {
|
|
232
|
+
kind: category,
|
|
233
|
+
safe: false,
|
|
234
|
+
input: {
|
|
235
|
+
suggestedAction,
|
|
236
|
+
...(context.resource ? { resource: context.resource } : {}),
|
|
237
|
+
...(context.operation ? { operation: context.operation } : {}),
|
|
238
|
+
},
|
|
239
|
+
},
|
|
240
|
+
};
|
|
241
|
+
}
|
|
242
|
+
/**
|
|
243
|
+
* Builds an AI-ready self-healing report from captured diagnostics, formatting
|
|
244
|
+
* the failure root-causes and providing a direct prompt for AI Agent remediation.
|
|
245
|
+
*/
|
|
246
|
+
export function buildSelfHealingReport(diagnostics, _events) {
|
|
247
|
+
const errorDiagnostics = diagnostics.filter((d) => d.severity === 'error');
|
|
248
|
+
const issues = errorDiagnostics.map((d) => {
|
|
249
|
+
let category = 'RUNTIME_EXCEPTION';
|
|
250
|
+
let suggestedAction = 'Inspect component logic and stack trace.';
|
|
251
|
+
const resource = d.fix?.input?.['resource'];
|
|
252
|
+
const operation = d.fix?.input?.['operation'];
|
|
253
|
+
if (d.fix?.kind &&
|
|
254
|
+
['PERMISSION_DENIED', 'SCHEMA_MISMATCH', 'NETWORK_ERROR', 'RUNTIME_EXCEPTION'].includes(d.fix.kind)) {
|
|
255
|
+
category = d.fix.kind;
|
|
256
|
+
suggestedAction = d.fix.input?.['suggestedAction'] || suggestedAction;
|
|
257
|
+
}
|
|
258
|
+
else if (/auth|forbidden|permission|403/i.test(d.code + ' ' + d.message)) {
|
|
259
|
+
category = 'PERMISSION_DENIED';
|
|
260
|
+
suggestedAction = 'Check AccessControlProvider or AuthProvider permissions.';
|
|
261
|
+
}
|
|
262
|
+
else if (/schema|type|validation/i.test(d.code + ' ' + d.message)) {
|
|
263
|
+
category = 'SCHEMA_MISMATCH';
|
|
264
|
+
suggestedAction = 'Check field definitions in ResourceDefinition against backend schema.';
|
|
265
|
+
}
|
|
266
|
+
else if (/network|404|500|fetch/i.test(d.code + ' ' + d.message)) {
|
|
267
|
+
category = 'NETWORK_ERROR';
|
|
268
|
+
suggestedAction = 'Check API endpoint URL and network connectivity.';
|
|
269
|
+
}
|
|
270
|
+
return {
|
|
271
|
+
category,
|
|
272
|
+
code: d.code,
|
|
273
|
+
message: d.message,
|
|
274
|
+
...(resource ? { resource } : {}),
|
|
275
|
+
...(operation ? { operation } : {}),
|
|
276
|
+
suggestedAction,
|
|
277
|
+
...(d.location ? { location: d.location } : {}),
|
|
278
|
+
};
|
|
279
|
+
});
|
|
280
|
+
const hasErrors = issues.length > 0;
|
|
281
|
+
const agentPrompt = hasErrors
|
|
282
|
+
? `## SVAdmin Runtime Error Self-Healing Report\n\nThe following ${issues.length} runtime error(s) were captured by SVAdmin DevTools:\n\n${issues
|
|
283
|
+
.map((issue, idx) => {
|
|
284
|
+
const target = issue.resource
|
|
285
|
+
? ` (Resource: ${issue.resource}${issue.operation ? `, Operation: ${issue.operation}` : ''})`
|
|
286
|
+
: '';
|
|
287
|
+
const loc = issue.location?.file
|
|
288
|
+
? ` at ${issue.location.file}:${issue.location.line ?? 1}`
|
|
289
|
+
: '';
|
|
290
|
+
return `${idx + 1}. [${issue.category}] ${issue.code}${target}${loc}: ${issue.message}\n Suggested Fix: ${issue.suggestedAction}`;
|
|
291
|
+
})
|
|
292
|
+
.join('\n')}\n\nPlease analyze the root causes and generate the exact code fix required to resolve these issues.`
|
|
293
|
+
: 'No active runtime errors found in SVAdmin DevTools.';
|
|
294
|
+
return {
|
|
295
|
+
hasErrors,
|
|
296
|
+
errorCount: issues.length,
|
|
297
|
+
issues,
|
|
298
|
+
agentPrompt,
|
|
299
|
+
};
|
|
300
|
+
}
|
|
301
|
+
/**
|
|
302
|
+
* Builds a structured writeback patch from visual inspector interactions,
|
|
303
|
+
* generating actionable code snippets and an Agent-executable prompt.
|
|
304
|
+
*/
|
|
305
|
+
export function buildResourcePatch(patch) {
|
|
306
|
+
const resource = patch.resource;
|
|
307
|
+
let summary;
|
|
308
|
+
let suggestedPatchCode;
|
|
309
|
+
let agentPrompt;
|
|
310
|
+
switch (patch.action) {
|
|
311
|
+
case 'toggleColumnVisibility': {
|
|
312
|
+
const col = patch.column ?? patch.field ?? 'unknown';
|
|
313
|
+
const isHidden = Boolean(patch.value);
|
|
314
|
+
summary = `${isHidden ? 'Hide' : 'Show'} column '${col}' in resource '${resource}' AutoTable`;
|
|
315
|
+
suggestedPatchCode = `// In resource definition for '${resource}':\ncolumns: [\n // ...\n { key: '${col}', hidden: ${isHidden} },\n]`;
|
|
316
|
+
agentPrompt = `[SVADMIN_WRITEBACK_PATCH]\nResource: ${resource}\nAction: toggleColumnVisibility\nTarget: column '${col}'\nSet hidden: ${isHidden}\nPlease update the ResourceDefinition or AutoTable columns in ${resource} page accordingly.`;
|
|
317
|
+
break;
|
|
318
|
+
}
|
|
319
|
+
case 'updateField': {
|
|
320
|
+
const field = patch.field ?? 'unknown';
|
|
321
|
+
const valStr = typeof patch.value === 'object' ? JSON.stringify(patch.value) : String(patch.value);
|
|
322
|
+
summary = `Update field '${field}' properties in resource '${resource}'`;
|
|
323
|
+
suggestedPatchCode = `// In resource definition for '${resource}':\nfields: [\n // ...\n { key: '${field}', ...${valStr} },\n]`;
|
|
324
|
+
agentPrompt = `[SVADMIN_WRITEBACK_PATCH]\nResource: ${resource}\nAction: updateField\nField: '${field}'\nPatch: ${valStr}\nPlease apply this field property change to resource '${resource}'.`;
|
|
325
|
+
break;
|
|
326
|
+
}
|
|
327
|
+
case 'updateColumnTitle': {
|
|
328
|
+
const col = patch.column ?? patch.field ?? 'unknown';
|
|
329
|
+
summary = `Change column '${col}' header title to '${patch.value}' in resource '${resource}'`;
|
|
330
|
+
suggestedPatchCode = `// In resource definition for '${resource}':\ncolumns: [\n // ...\n { key: '${col}', title: '${patch.value}' },\n]`;
|
|
331
|
+
agentPrompt = `[SVADMIN_WRITEBACK_PATCH]\nResource: ${resource}\nAction: updateColumnTitle\nColumn: '${col}'\nNew title: '${patch.value}'\nPlease update the column title in resource '${resource}'.`;
|
|
332
|
+
break;
|
|
333
|
+
}
|
|
334
|
+
case 'updatePageSize': {
|
|
335
|
+
summary = `Update default page size for resource '${resource}' to ${patch.value}`;
|
|
336
|
+
suggestedPatchCode = `// In resource definition for '${resource}':\npagination: { defaultPageSize: ${patch.value} }`;
|
|
337
|
+
agentPrompt = `[SVADMIN_WRITEBACK_PATCH]\nResource: ${resource}\nAction: updatePageSize\nPageSize: ${patch.value}\nPlease update pagination defaultPageSize to ${patch.value} for resource '${resource}'.`;
|
|
338
|
+
break;
|
|
339
|
+
}
|
|
340
|
+
default: {
|
|
341
|
+
summary = `Apply ${patch.action} to resource '${resource}'`;
|
|
342
|
+
suggestedPatchCode = `// Patch ${JSON.stringify(patch)}`;
|
|
343
|
+
agentPrompt = `[SVADMIN_WRITEBACK_PATCH]\n${JSON.stringify(patch, null, 2)}`;
|
|
344
|
+
}
|
|
345
|
+
}
|
|
346
|
+
return {
|
|
347
|
+
success: true,
|
|
348
|
+
patch,
|
|
349
|
+
summary,
|
|
350
|
+
suggestedPatchCode,
|
|
351
|
+
agentPrompt,
|
|
352
|
+
};
|
|
353
|
+
}
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@svadmin/devtools",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.6.1",
|
|
4
4
|
"type": "module",
|
|
5
5
|
"description": "Headless diagnostics core for svadmin — query traces, provider diagnostics, permission/resource/route inspection",
|
|
6
6
|
"license": "MIT",
|
|
@@ -47,7 +47,7 @@
|
|
|
47
47
|
"@svadmin/devtools-contract": "^0.3.1"
|
|
48
48
|
},
|
|
49
49
|
"peerDependencies": {
|
|
50
|
-
"@svadmin/core": "^0.
|
|
50
|
+
"@svadmin/core": "^0.72.0"
|
|
51
51
|
},
|
|
52
52
|
"peerDependenciesMeta": {
|
|
53
53
|
"@svadmin/core": {
|