@cloudcare/guance-front-tools 1.0.17 → 1.0.18
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/README.md +55 -0
- package/package.json +1 -1
- package/skills/grafana-to-guance-dashboard/SKILL.md +32 -1
package/README.md
CHANGED
|
@@ -25,3 +25,58 @@ import { covert } from '@cloudcare/guance-front-tools'
|
|
|
25
25
|
|
|
26
26
|
const guanceDashboard = covert(grafanaDashboard)
|
|
27
27
|
```
|
|
28
|
+
|
|
29
|
+
## AI Skill Usage
|
|
30
|
+
|
|
31
|
+
This repository also ships a Codex skill for Grafana-to-Guance dashboard conversion:
|
|
32
|
+
|
|
33
|
+
- skill manifest:
|
|
34
|
+
- `skills/grafana-to-guance-dashboard/SKILL.md`
|
|
35
|
+
- executable skill script:
|
|
36
|
+
- `skills/grafana-to-guance-dashboard/scripts/convert-grafana-dashboard.mjs`
|
|
37
|
+
- skill converter core:
|
|
38
|
+
- `skills/grafana-to-guance-dashboard/scripts/convert-grafana-dashboard-core.js`
|
|
39
|
+
|
|
40
|
+
When an AI agent is working inside this repository and needs to convert or debug Grafana dashboards, it should use that skill and run the standalone skill script from the repository root:
|
|
41
|
+
|
|
42
|
+
```bash
|
|
43
|
+
node skills/grafana-to-guance-dashboard/scripts/convert-grafana-dashboard.mjs \
|
|
44
|
+
--input path/to/grafana-dashboard.json \
|
|
45
|
+
--output path/to/guance-dashboard.json \
|
|
46
|
+
--validate
|
|
47
|
+
```
|
|
48
|
+
|
|
49
|
+
Optional modes:
|
|
50
|
+
|
|
51
|
+
```bash
|
|
52
|
+
node skills/grafana-to-guance-dashboard/scripts/convert-grafana-dashboard.mjs \
|
|
53
|
+
--input path/to/grafana-dashboard.json \
|
|
54
|
+
--output path/to/guance-dashboard.guance-promql.json \
|
|
55
|
+
--validate \
|
|
56
|
+
--guance-promql-compatible
|
|
57
|
+
|
|
58
|
+
node skills/grafana-to-guance-dashboard/scripts/convert-grafana-dashboard.mjs \
|
|
59
|
+
--input path/to/grafana-dashboard.json \
|
|
60
|
+
--output path/to/guance-dashboard.keep-meta.json \
|
|
61
|
+
--validate \
|
|
62
|
+
--keep-grafana-meta
|
|
63
|
+
```
|
|
64
|
+
|
|
65
|
+
Implementation notes for AI agents:
|
|
66
|
+
|
|
67
|
+
- Do not hand-edit the generated skill copies first.
|
|
68
|
+
- For conversion logic changes, edit:
|
|
69
|
+
- `lib/scripts/convert-grafana-dashboard-core.js`
|
|
70
|
+
- For CLI / validation behavior changes, edit:
|
|
71
|
+
- `lib/scripts/convert-grafana-dashboard.js`
|
|
72
|
+
- After changing either file, sync the skill and published copies:
|
|
73
|
+
|
|
74
|
+
```bash
|
|
75
|
+
node scripts/sync-converter.mjs
|
|
76
|
+
```
|
|
77
|
+
|
|
78
|
+
Or rebuild everything:
|
|
79
|
+
|
|
80
|
+
```bash
|
|
81
|
+
npm run build
|
|
82
|
+
```
|
package/package.json
CHANGED
|
@@ -45,6 +45,38 @@ node skills/grafana-to-guance-dashboard/scripts/convert-grafana-dashboard.mjs \
|
|
|
45
45
|
--keep-grafana-meta
|
|
46
46
|
```
|
|
47
47
|
|
|
48
|
+
## Script Layout
|
|
49
|
+
|
|
50
|
+
The skill script directory contains two files:
|
|
51
|
+
|
|
52
|
+
- `skills/grafana-to-guance-dashboard/scripts/convert-grafana-dashboard.mjs`
|
|
53
|
+
- executable wrapper
|
|
54
|
+
- parses CLI args
|
|
55
|
+
- validates output against local schemas
|
|
56
|
+
- imports `./convert-grafana-dashboard-core.js`
|
|
57
|
+
- `skills/grafana-to-guance-dashboard/scripts/convert-grafana-dashboard-core.js`
|
|
58
|
+
- pure conversion logic
|
|
59
|
+
- no file-system or schema-validation responsibilities
|
|
60
|
+
|
|
61
|
+
## How To Edit
|
|
62
|
+
|
|
63
|
+
Do not hand-edit the generated skill script copies unless you are explicitly debugging the skill directory itself.
|
|
64
|
+
|
|
65
|
+
- For conversion behavior changes:
|
|
66
|
+
- edit `lib/scripts/convert-grafana-dashboard-core.js`
|
|
67
|
+
- For CLI / validation behavior changes:
|
|
68
|
+
- edit `lib/scripts/convert-grafana-dashboard.js`
|
|
69
|
+
- After editing either one:
|
|
70
|
+
- run `node scripts/sync-converter.mjs`
|
|
71
|
+
- or run `npm run build`
|
|
72
|
+
|
|
73
|
+
The sync step copies the repository wrapper/core into:
|
|
74
|
+
|
|
75
|
+
- `skills/grafana-to-guance-dashboard/scripts/convert-grafana-dashboard.mjs`
|
|
76
|
+
- `skills/grafana-to-guance-dashboard/scripts/convert-grafana-dashboard-core.js`
|
|
77
|
+
|
|
78
|
+
The synced outputs are transpiled to avoid syntax such as `?.` and `??` in published/skill-facing files.
|
|
79
|
+
|
|
48
80
|
## What The Standalone Skill Converter Supports
|
|
49
81
|
|
|
50
82
|
- Grafana variables of type `query`, `custom`, `textbox`, `constant`, `interval`, and `datasource`
|
|
@@ -85,7 +117,6 @@ When conversion fails or output is incomplete, read [references/converter-notes.
|
|
|
85
117
|
|
|
86
118
|
## Editing Rules
|
|
87
119
|
|
|
88
|
-
- Prefer patching `skills/grafana-to-guance-dashboard/scripts/convert-grafana-dashboard.mjs` for conversion behavior.
|
|
89
120
|
- Only change schemas when the generated Guance JSON is valid real data but the schema is too strict.
|
|
90
121
|
- Keep validation green:
|
|
91
122
|
- `npm run validate`
|