@cloudcare/guance-front-tools 1.0.17 → 1.0.19

package/README.md

@@ -25,3 +25,67 @@ import { covert } from '@cloudcare/guance-front-tools'
 
 const guanceDashboard = covert(grafanaDashboard)
 ```
+
+## AI Skill Usage
+
+This repository also ships a Codex skill for Grafana-to-Guance dashboard conversion:
+
+- skill manifest:
+  - `skills/grafana-to-guance-dashboard/SKILL.md`
+- executable skill script:
+  - `skills/grafana-to-guance-dashboard/scripts/convert-grafana-dashboard.mjs`
+- skill converter core:
+  - `skills/grafana-to-guance-dashboard/scripts/convert-grafana-dashboard-core.js`
+- standalone validator:
+  - `skills/grafana-to-guance-dashboard/scripts/validate-file.mjs`
+- bundled schemas, fixtures, and tests:
+  - `skills/grafana-to-guance-dashboard/schemas/`
+  - `skills/grafana-to-guance-dashboard/fixtures/`
+  - `skills/grafana-to-guance-dashboard/test/`
+
+When an AI agent needs to convert or debug Grafana dashboards with the standalone skill, it should work inside the skill directory:
+
+```bash
+cd skills/grafana-to-guance-dashboard
+npm install
+npm run convert -- \
+  --input ./fixtures/grafana-dashboard.json \
+  --output ./output/guance-dashboard.json \
+  --validate
+```
+
+Optional modes:
+
+```bash
+npm run convert -- \
+  --input ./fixtures/grafana-dashboard.json \
+  --output ./output/guance-dashboard.guance-promql.json \
+  --validate \
+  --guance-promql-compatible
+
+npm run convert -- \
+  --input ./fixtures/grafana-dashboard.json \
+  --output ./output/guance-dashboard.keep-meta.json \
+  --validate \
+  --keep-grafana-meta
+```
+
+Implementation notes for AI agents:
+
+- The skill is self-contained and no longer syncs from `lib/scripts/*`.
+- The skill is intended to do more than execute conversion:
+  - preflight analysis
+  - unit inference review
+  - PromQL compatibility audit
+  - post-conversion gap analysis
+  - repair planning
+- For skill conversion logic changes, edit:
+  - `skills/grafana-to-guance-dashboard/scripts/convert-grafana-dashboard-core.js`
+- For skill CLI / validation behavior changes, edit:
+  - `skills/grafana-to-guance-dashboard/scripts/convert-grafana-dashboard.mjs`
+- Validate and regression-test inside the skill directory:
+
+```bash
+npm run validate:file -- ./output/guance-dashboard.json
+npm test
+```

package/lib/cjs/package.json

@@ -0,0 +1,3 @@
+{
+  "type": "commonjs"
+}

package/lib/cjs/scripts/convert-grafana-dashboard.js

@@ -1,23 +1,17 @@
 #!/usr/bin/env node
 "use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.convertDashboard = void 0;
 exports.main = main;
 exports.validateDashboardFile = validateDashboardFile;
-const fs_1 = require("fs");
-const path_1 = require("path");
-const url_1 = require("url");
-const ajv_1 = require("ajv");
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const ajv_1 = __importDefault(require("ajv"));
 const convert_grafana_dashboard_core_js_1 = require("./convert-grafana-dashboard-core.js");
 Object.defineProperty(exports, "convertDashboard", { enumerable: true, get: function () { return convert_grafana_dashboard_core_js_1.convertDashboard; } });
-if (isDirectExecution()) {
-    main();
-}
-function isDirectExecution() {
-    if (!process.argv[1])
-        return false;
-    return import.meta.url === (0, url_1.pathToFileURL)(path_1.default.resolve(process.argv[1])).href;
-}
 function main() {
     const { inputPath, outputPath, validateOutput, schemaId, guancePromqlCompatible, keepGrafanaMeta } = parseArgs(process.argv.slice(2));
     const grafanaDashboard = readJson(inputPath);

package/lib/esm/package.json

@@ -0,0 +1,3 @@
+{
+  "type": "module"
+}

package/lib/esm/scripts/convert-grafana-dashboard.js

@@ -1,17 +1,8 @@
 #!/usr/bin/env node
 import fs from 'fs';
 import path from 'path';
-import { pathToFileURL } from 'url';
 import Ajv from 'ajv';
 import { convertDashboard } from './convert-grafana-dashboard-core.js';
-if (isDirectExecution()) {
-    main();
-}
-function isDirectExecution() {
-    if (!process.argv[1])
-        return false;
-    return import.meta.url === pathToFileURL(path.resolve(process.argv[1])).href;
-}
 export function main() {
     const { inputPath, outputPath, validateOutput, schemaId, guancePromqlCompatible, keepGrafanaMeta } = parseArgs(process.argv.slice(2));
     const grafanaDashboard = readJson(inputPath);

package/lib/scripts/convert-grafana-dashboard.js

@@ -2,19 +2,9 @@
 
 import fs from 'fs'
 import path from 'path'
-import { pathToFileURL } from 'url'
 import Ajv from 'ajv'
 import { convertDashboard } from './convert-grafana-dashboard-core.js'
 
-if (isDirectExecution()) {
-  main()
-}
-
-function isDirectExecution() {
-  if (!process.argv[1]) return false
-  return import.meta.url === pathToFileURL(path.resolve(process.argv[1])).href
-}
-
 export function main() {
   const { inputPath, outputPath, validateOutput, schemaId, guancePromqlCompatible, keepGrafanaMeta } = parseArgs(process.argv.slice(2))
   const grafanaDashboard = readJson(inputPath)

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@cloudcare/guance-front-tools",
-    "version": "1.0.17",
+    "version": "1.0.19",
     "publishConfig": {
         "access": "public"
     },
@@ -16,11 +16,13 @@
     "types": "lib/cjs/src/index.d.ts",
     "module": "lib/esm/src/index.js",
     "scripts": {
-        "build": "npm run clean && npm run generate && npm run build:cjs && npm run build:esm && npm run build:script && npm run sync:converter",
+        "build": "npm run clean && npm run generate && npm run build:cjs && npm run build:esm && npm run build:script && npm run build:cjs:scripts && npm run build:esm:scripts && npm run write:module-package-json",
         "build:cjs": "tsc -p tsconfig.cjs.json",
+        "build:cjs:scripts": "tsc -p tsconfig.cjs.scripts.json",
         "build:esm": "tsc -p tsconfig.esm.json",
+        "build:esm:scripts": "tsc -p tsconfig.esm.scripts.json",
         "build:script": "tsc -p tsconfig.script.json",
-        "sync:converter": "node scripts/sync-converter.mjs",
+        "write:module-package-json": "node scripts/write-module-package-json.mjs",
         "clean": "rm -rf ./lib/generated && rm -rf ./lib/esm && rm -rf ./lib/cjs",
         "generate": "node scripts/generate.mjs",
         "test": "node --test test/*.test.mjs",

package/scripts/write-module-package-json.mjs

@@ -0,0 +1,24 @@
+import fs from 'fs'
+import path from 'path'
+
+const projectRoot = process.cwd()
+const packageBoundaries = [
+  {
+    filePath: path.join(projectRoot, 'lib', 'cjs', 'package.json'),
+    content: {
+      type: 'commonjs',
+    },
+  },
+  {
+    filePath: path.join(projectRoot, 'lib', 'esm', 'package.json'),
+    content: {
+      type: 'module',
+    },
+  },
+]
+
+for (const { filePath, content } of packageBoundaries) {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true })
+  fs.writeFileSync(filePath, `${JSON.stringify(content, null, 2)}\n`, 'utf8')
+  console.log(`Wrote ${path.relative(projectRoot, filePath)}`)
+}