@cargo-ai/cli 1.0.41 → 1.0.43

package/build/commands/observability/alert.d.ts

@@ -0,0 +1,4 @@
+import type { Command } from "commander";
+import type { Api } from "../../api.js";
+export declare function registerAlertCommands(parent: Command, getApi: () => Api): void;
+//# sourceMappingURL=alert.d.ts.map

package/build/commands/observability/alert.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"alert.d.ts","sourceRoot":"","sources":["../../../src/commands/observability/alert.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEzC,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,cAAc,CAAC;AA0BxC,wBAAgB,qBAAqB,CACnC,MAAM,EAAE,OAAO,EACf,MAAM,EAAE,MAAM,GAAG,GAChB,IAAI,CAsMN"}

package/build/commands/observability/alert.js

@@ -0,0 +1,131 @@
+import { ExitCodes, failWith, handleApiCall, outputJson, parseJson, } from "../runHandler.js";
+// Strict on purpose: `--enabled yes` silently DISABLING the alert (anything
+// but the literal "true" used to read as false) is the kind of surprise a
+// usage error prevents.
+function parseBooleanOption(value, optionName) {
+    if (value === "true") {
+        return true;
+    }
+    if (value === "false") {
+        return false;
+    }
+    failWith(`${optionName} must be "true" or "false", got "${value}".`, {
+        code: ExitCodes.InvalidUsage,
+    });
+}
+export function registerAlertCommands(parent, getApi) {
+    const alert = parent
+        .command("alert")
+        .description("Alert operations (scheduled threshold alerts on spans, runs, records, SQL or a model)");
+    alert
+        .command("list")
+        .description("List all alerts")
+        .action(async () => {
+        const api = getApi();
+        const result = await handleApiCall(() => api.observability.alert.list());
+        outputJson(result);
+    });
+    alert
+        .command("get <uuid>")
+        .description("Get an alert")
+        .action(async (uuid) => {
+        const api = getApi();
+        const result = await handleApiCall(() => api.observability.alert.get(uuid));
+        outputJson(result);
+    });
+    alert
+        .command("create")
+        .description("Create an alert")
+        .requiredOption("--name <name>", "Alert name")
+        .requiredOption("--cron <cron>", 'Evaluation schedule: 5-field cron or "@every <interval>" (UTC), at most once a minute')
+        .requiredOption("--scope <json>", 'Scope (JSON), one of: {"kind":"spans","workflowUuid":"..."}, {"kind":"runs","workflowUuid":"...","statuses":["error"]}, {"kind":"records","workflowUuid":"...","statuses":["error"]}, {"kind":"orchestrationQuery","query":"select ..."}, {"kind":"storageQuery","query":"select ..."} or {"kind":"model","modelUuid":"...","filter":{...}}')
+        .requiredOption("--threshold <json>", 'Threshold (JSON). Spans, runs and records scopes: {"metric":"errorRate","operator":"gte","value":10}, {"metric":"duration","aggregation":"p95","operator":"gte","value":30}, {"metric":"credits","aggregation":"sum","operator":"gte","value":500} or {"metric":"count","operator":"lte","value":0}; model scopes: {"metric":"recordsCount","operator":"lte","value":0}, {"metric":"recordsShare","operator":"gte","value":30} (needs a scope filter), {"metric":"freshness","operator":"gte","value":60} or {"metric":"syncDuration","operator":"gte","value":300}; query scopes: {"metric":"query","operator":"gte","value":10}')
+        .option("--actions <json>", "Actions fired as runs on breach (JSON Action[]: connector, tool, or agent nodes)")
+        .option("--disabled", "Create the alert disabled")
+        .option("--description <text>", "What this alert watches")
+        .option("--folder <uuid>", "Folder UUID to file the alert under")
+        .action(async (opts) => {
+        const api = getApi();
+        const result = await handleApiCall(() => api.observability.alert.create({
+            name: opts.name,
+            description: opts.description,
+            cron: opts.cron,
+            isEnabled: opts.disabled === true ? false : undefined,
+            scope: parseJson(opts.scope, "--scope"),
+            threshold: parseJson(opts.threshold, "--threshold"),
+            actions: opts.actions !== undefined
+                ? parseJson(opts.actions, "--actions")
+                : undefined,
+            folderUuid: opts.folder,
+        }));
+        outputJson(result);
+    });
+    alert
+        .command("update")
+        .description("Update an alert")
+        .requiredOption("--uuid <uuid>", "Alert UUID")
+        .option("--name <name>", "Alert name")
+        .option("--cron <cron>", 'Evaluation schedule: 5-field cron or "@every <interval>" (UTC), at most once a minute')
+        .option("--enabled <boolean>", "Enable or disable the alert (true/false)")
+        .option("--scope <json>", "Scope (JSON). See `alert create`")
+        .option("--threshold <json>", "Threshold (JSON). See `alert create`")
+        .option("--actions <json>", "Actions fired as runs on breach (JSON Action[])")
+        .option("--description <text>", 'What this alert watches, or "none" to clear it')
+        .option("--folder <uuid>", 'Folder UUID to move the alert to, or "none" to remove it from its folder')
+        .action(async (opts) => {
+        const api = getApi();
+        const result = await handleApiCall(() => api.observability.alert.update({
+            uuid: opts.uuid,
+            name: opts.name,
+            cron: opts.cron,
+            isEnabled: opts.enabled !== undefined
+                ? parseBooleanOption(opts.enabled, "--enabled")
+                : undefined,
+            scope: opts.scope !== undefined
+                ? parseJson(opts.scope, "--scope")
+                : undefined,
+            threshold: opts.threshold !== undefined
+                ? parseJson(opts.threshold, "--threshold")
+                : undefined,
+            actions: opts.actions !== undefined
+                ? parseJson(opts.actions, "--actions")
+                : undefined,
+            description: opts.description === undefined
+                ? undefined
+                : opts.description === "none"
+                    ? null
+                    : opts.description,
+            // "none" is the explicit "take it out of its folder" spelling —
+            // omitting --folder leaves the alert where it is.
+            folderUuid: opts.folder === undefined
+                ? undefined
+                : opts.folder === "none"
+                    ? null
+                    : opts.folder,
+        }));
+        outputJson(result);
+    });
+    alert
+        .command("remove <uuid>")
+        .description("Remove an alert")
+        .action(async (uuid) => {
+        const api = getApi();
+        await handleApiCall(() => api.observability.alert.remove(uuid));
+        outputJson({ ok: true });
+    });
+    alert
+        .command("preview")
+        .description("Evaluate a scope + threshold now, without firing actions")
+        .requiredOption("--scope <json>", "Scope (JSON). See `alert create`")
+        .requiredOption("--threshold <json>", "Threshold (JSON). See `alert create`")
+        .option("--window-minutes <minutes>", "Evaluation window ending now (spans, runs and records scopes only; a model is measured as it stands, and a query windows itself)", "60")
+        .action(async (opts) => {
+        const api = getApi();
+        const result = await handleApiCall(() => api.observability.alert.preview({
+            scope: parseJson(opts.scope, "--scope"),
+            threshold: parseJson(opts.threshold, "--threshold"),
+            windowMinutes: parseInt(opts.windowMinutes, 10),
+        }));
+        outputJson(result);
+    });
+}

package/build/commands/observability/event.d.ts

@@ -0,0 +1,4 @@
+import type { Command } from "commander";
+import type { Api } from "../../api.js";
+export declare function registerEventCommands(parent: Command, getApi: () => Api): void;
+//# sourceMappingURL=event.d.ts.map

package/build/commands/observability/event.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"event.d.ts","sourceRoot":"","sources":["../../../src/commands/observability/event.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEzC,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,cAAc,CAAC;AAGxC,wBAAgB,qBAAqB,CACnC,MAAM,EAAE,OAAO,EACf,MAAM,EAAE,MAAM,GAAG,GAChB,IAAI,CAaN"}

package/build/commands/observability/event.js

@@ -0,0 +1,12 @@
+import { handleApiCall, outputJson } from "../runHandler.js";
+export function registerEventCommands(parent, getApi) {
+    const event = parent.command("event").description("Alert evaluation events");
+    event
+        .command("list <alertUuid>")
+        .description("List the latest evaluation events of an alert")
+        .action(async (alertUuid) => {
+        const api = getApi();
+        const result = await handleApiCall(() => api.observability.event.list({ alertUuid }));
+        outputJson(result);
+    });
+}

package/build/commands/observability/index.d.ts

@@ -0,0 +1,4 @@
+import type { Command } from "commander";
+import type { Api } from "../../api.js";
+export declare function registerObservabilityCommands(parent: Command, getApi: () => Api): void;
+//# sourceMappingURL=index.d.ts.map

package/build/commands/observability/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/commands/observability/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEzC,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,cAAc,CAAC;AAIxC,wBAAgB,6BAA6B,CAC3C,MAAM,EAAE,OAAO,EACf,MAAM,EAAE,MAAM,GAAG,GAChB,IAAI,CAON"}

package/build/commands/observability/index.js

@@ -0,0 +1,9 @@
+import { registerAlertCommands } from "./alert.js";
+import { registerEventCommands } from "./event.js";
+export function registerObservabilityCommands(parent, getApi) {
+    const observability = parent
+        .command("observability")
+        .description("Alerts and alert events");
+    registerAlertCommands(observability, getApi);
+    registerEventCommands(observability, getApi);
+}

package/build/commands/orchestration/query.js

@@ -2,11 +2,11 @@ import { handleApiCall, outputJson } from "../runHandler.js";
 export function registerQueryCommands(parent, getApi) {
     const query = parent
         .command("query")
-        .description("Execute SQL queries against orchestration tables");
+        .description("Execute ClickHouse SQL queries against orchestration tables");
     query
         .command("execute")
-        .description("Execute a read-only SQL query")
-        .argument("<sql>", "SQL query string")
+        .description("Execute a read-only ClickHouse SQL query")
+        .argument("<sql>", "ClickHouse SQL query string")
         .addHelpText("after", `
 Available tables: spans, runs, batches, records
 

package/build/index.js

@@ -14,6 +14,7 @@ import { registerExpressionCommands } from "./commands/expression/index.js";
 import { registerHostingCommands } from "./commands/hosting/index.js";
 import { registerInitCommand } from "./commands/init.js";
 import { registerMcpCommand } from "./commands/mcp.js";
+import { registerObservabilityCommands } from "./commands/observability/index.js";
 import { registerOrchestrationCommands } from "./commands/orchestration/index.js";
 import { registerRevenueOrganizationCommands } from "./commands/revenueOrganization/index.js";
 import { ExitCodes, failWith } from "./commands/runHandler.js";
@@ -62,6 +63,7 @@ registerAuthCommands(program, getApi);
 registerVersionCommand(program, version);
 registerDoctorCommand(program, version);
 registerInitCommand(program, getApi);
+registerObservabilityCommands(program, getApi);
 registerOrchestrationCommands(program, getApi);
 registerWorkspaceManagementCommands(program, getApi);
 registerStorageCommands(program, getApi);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cargo-ai/cli",
-  "version": "1.0.41",
+  "version": "1.0.43",
   "private": false,
   "license": "UNLICENSED",
   "description": "Command-line interface for the Cargo API",
@@ -30,7 +30,7 @@
     "format:check": "prettier --check ."
   },
   "dependencies": {
-    "@cargo-ai/api": "^1.0.52",
+    "@cargo-ai/api": "^1.0.54",
     "@cargo-ai/app-sdk": "^1.0.5",
     "@cargo-ai/cdk": "*",
     "@cargo-ai/types": "*",