@finebi/finebi-cli 1.2.1 → 1.3.0

package/skills/finebi-cli-agent/scripts/finebi-cli/src/error-catalog.js

@@ -0,0 +1,482 @@
+export const ERROR_CATALOG = [
+    {
+        code: "SKILL_INSTALL_FAILED",
+        layer: "node",
+        origin: "install-skill",
+        category: "configuration",
+        recoverableByAgent: false,
+        defaultRetryable: false,
+        pathSemantics: "Local Skill directory or installation record",
+        canonicalNextActions: ["finebi-cli install-skill --help"],
+        expectedAgentBehaviors: ["inspect the installation result and preserve local edits", "request explicit replacement before overwriting local changes"],
+        benchmarkTags: ["skills", "installation"],
+    },
+    {
+        code: "BROWSER_AUTH_URL_INVALID",
+        layer: "node",
+        origin: "browser-auth",
+        category: "configuration",
+        recoverableByAgent: true,
+        defaultRetryable: false,
+        pathSemantics: "Browser authorization base URL",
+        canonicalNextActions: ["finebi-cli config set base-url <https-url>"],
+        expectedAgentBehaviors: ["configure an HTTPS URL or localhost HTTP URL", "rerun browser login"],
+        benchmarkTags: ["auth", "browser", "url-validation"],
+    },
+    {
+        code: "BROWSER_AUTH_START_INVALID",
+        layer: "node",
+        origin: "browser-auth",
+        category: "contract",
+        recoverableByAgent: false,
+        defaultRetryable: false,
+        pathSemantics: "Browser authorization start response field",
+        canonicalNextActions: ["finebi-cli auth login --browser"],
+        expectedAgentBehaviors: ["report browser authorization contract mismatch"],
+        benchmarkTags: ["auth", "browser", "contract-mismatch"],
+    },
+    {
+        code: "BROWSER_AUTH_POLL_INVALID",
+        layer: "node",
+        origin: "browser-auth",
+        category: "contract",
+        recoverableByAgent: false,
+        defaultRetryable: false,
+        pathSemantics: "Browser authorization poll response field",
+        canonicalNextActions: ["finebi-cli auth login --browser"],
+        expectedAgentBehaviors: ["report browser authorization contract mismatch"],
+        benchmarkTags: ["auth", "browser", "contract-mismatch"],
+    },
+    {
+        code: "BROWSER_AUTH_DENIED",
+        layer: "node",
+        origin: "browser-auth",
+        category: "authentication",
+        recoverableByAgent: true,
+        defaultRetryable: false,
+        pathSemantics: "Browser authorization status",
+        canonicalNextActions: ["finebi-cli auth login --browser"],
+        expectedAgentBehaviors: ["request a new browser authorization"],
+        benchmarkTags: ["auth", "browser", "denied"],
+    },
+    {
+        code: "BROWSER_AUTH_EXPIRED",
+        layer: "node",
+        origin: "browser-auth",
+        category: "authentication",
+        recoverableByAgent: true,
+        defaultRetryable: false,
+        pathSemantics: "Browser authorization status",
+        canonicalNextActions: ["finebi-cli auth login --browser"],
+        expectedAgentBehaviors: ["request a new browser authorization"],
+        benchmarkTags: ["auth", "browser", "expired"],
+    },
+    {
+        code: "BROWSER_AUTH_CONSUMED",
+        layer: "node",
+        origin: "browser-auth",
+        category: "authentication",
+        recoverableByAgent: true,
+        defaultRetryable: false,
+        pathSemantics: "Browser authorization status",
+        canonicalNextActions: ["finebi-cli auth login --browser"],
+        expectedAgentBehaviors: ["request a new browser authorization"],
+        benchmarkTags: ["auth", "browser", "consumed"],
+    },
+    {
+        code: "BROWSER_AUTH_ABORTED",
+        layer: "node",
+        origin: "browser-auth",
+        category: "authentication",
+        recoverableByAgent: true,
+        defaultRetryable: false,
+        pathSemantics: "Browser authorization lifecycle",
+        canonicalNextActions: ["finebi-cli auth login --browser"],
+        expectedAgentBehaviors: ["request a new browser authorization"],
+        benchmarkTags: ["auth", "browser", "aborted"],
+    },
+    {
+        code: "BROWSER_AUTH_TIMEOUT",
+        layer: "node",
+        origin: "browser-auth",
+        category: "authentication",
+        recoverableByAgent: true,
+        defaultRetryable: false,
+        pathSemantics: "Browser authorization expiry",
+        canonicalNextActions: ["finebi-cli auth login --browser"],
+        expectedAgentBehaviors: ["request a new browser authorization"],
+        benchmarkTags: ["auth", "browser", "timeout"],
+    },
+    {
+        code: "BROWSER_AUTH_RATE_LIMITED",
+        layer: "node",
+        origin: "browser-auth",
+        category: "http",
+        recoverableByAgent: true,
+        defaultRetryable: true,
+        pathSemantics: "Browser authorization poll endpoint",
+        canonicalNextActions: ["Wait before polling again"],
+        expectedAgentBehaviors: ["back off polling"],
+        benchmarkTags: ["auth", "browser", "rate-limit"],
+    },
+    {
+        code: "BROWSER_AUTH_HTTP_ERROR",
+        layer: "node",
+        origin: "browser-auth",
+        category: "http",
+        recoverableByAgent: false,
+        defaultRetryable: false,
+        pathSemantics: "Browser authorization endpoint",
+        canonicalNextActions: ["finebi-cli auth login --browser"],
+        expectedAgentBehaviors: ["inspect the server response", "retry only when the service is available"],
+        benchmarkTags: ["auth", "browser", "http"],
+    },
+    {
+        code: "BROWSER_AUTH_SAVE_FAILED",
+        layer: "node",
+        origin: "browser-auth",
+        category: "local-state",
+        recoverableByAgent: true,
+        defaultRetryable: false,
+        pathSemantics: "Stored auth.accessKey",
+        canonicalNextActions: ["finebi-cli auth login --browser"],
+        expectedAgentBehaviors: ["fix local configuration write access", "retry browser login"],
+        benchmarkTags: ["auth", "browser", "local-state"],
+    },
+    {
+        code: "CONFIG_MISSING",
+        layer: "node",
+        origin: "config",
+        category: "configuration",
+        recoverableByAgent: true,
+        defaultRetryable: false,
+        pathSemantics: "Config field name",
+        canonicalNextActions: ["finebi-cli config set base-url <baseUrl>"],
+        expectedAgentBehaviors: ["run config set base-url", "rerun original command"],
+        benchmarkTags: ["config", "setup", "self-recovery"],
+    },
+    {
+        code: "AUTH_REQUIRED",
+        layer: "node",
+        origin: "auth",
+        category: "authentication",
+        recoverableByAgent: true,
+        defaultRetryable: false,
+        pathSemantics: "Auth config field",
+        canonicalNextActions: ["finebi-cli auth login --username <username>"],
+        expectedAgentBehaviors: ["run auth login", "rerun original command"],
+        benchmarkTags: ["auth", "setup", "self-recovery"],
+    },
+    {
+        code: "AUTH_EXPIRED",
+        layer: "node",
+        origin: "auth",
+        category: "authentication",
+        recoverableByAgent: true,
+        defaultRetryable: false,
+        pathSemantics: "Auth token expiry field",
+        canonicalNextActions: ["finebi-cli auth login --username <username>"],
+        expectedAgentBehaviors: ["run auth login", "rerun original command"],
+        benchmarkTags: ["auth", "token-expiry", "self-recovery"],
+    },
+    {
+        code: "AUTHENTICATION_FAILED",
+        layer: "node",
+        origin: "auth",
+        category: "authentication",
+        recoverableByAgent: true,
+        defaultRetryable: true,
+        pathSemantics: "Request URL path",
+        canonicalNextActions: ["finebi-cli auth login"],
+        expectedAgentBehaviors: ["run auth login", "rerun original command"],
+        benchmarkTags: ["auth", "access-key", "self-recovery"],
+    },
+    {
+        code: "PASSWORD_INPUT_FAILED",
+        layer: "node",
+        origin: "auth",
+        category: "authentication",
+        recoverableByAgent: true,
+        defaultRetryable: false,
+        pathSemantics: "Password input method",
+        canonicalNextActions: [
+            "finebi-cli auth login --from-env",
+            "echo <password> | finebi-cli auth login --username <username> --password-stdin",
+        ],
+        expectedAgentBehaviors: ["switch to --from-env", "provide FINEBI_PASSWORD env var"],
+        benchmarkTags: ["auth", "password", "self-recovery"],
+    },
+    {
+        code: "NETWORK_ERROR",
+        layer: "node",
+        origin: "http-client",
+        category: "network",
+        recoverableByAgent: false,
+        defaultRetryable: true,
+        pathSemantics: "Request URL path",
+        canonicalNextActions: [
+            "finebi-cli config set base-url <baseUrl>",
+            "finebi-cli auth login --username <username>",
+        ],
+        expectedAgentBehaviors: ["check base-url config", "retry after network issue is resolved"],
+        benchmarkTags: ["network", "transient"],
+    },
+    {
+        code: "AUTH_REDIRECT_OR_HTML_RESPONSE",
+        layer: "node",
+        origin: "http-client",
+        category: "authentication",
+        recoverableByAgent: true,
+        defaultRetryable: true,
+        pathSemantics: "Request URL path",
+        canonicalNextActions: ["finebi-cli auth login", "finebi-cli capability refresh"],
+        expectedAgentBehaviors: ["run auth login", "rerun original command"],
+        benchmarkTags: ["auth", "session-expired", "self-recovery"],
+    },
+    {
+        code: "HTTP_ERROR",
+        layer: "node",
+        origin: "http-client",
+        category: "http",
+        recoverableByAgent: false,
+        defaultRetryable: false,
+        pathSemantics: "Request URL path",
+        canonicalNextActions: ["finebi-cli capability refresh"],
+        expectedAgentBehaviors: ["check server logs", "inspect HTTP status code"],
+        benchmarkTags: ["http", "server-error"],
+    },
+    {
+        code: "HTTP_HTML_RESPONSE",
+        layer: "node",
+        origin: "http-client",
+        category: "http",
+        recoverableByAgent: false,
+        defaultRetryable: false,
+        pathSemantics: "Request URL path",
+        canonicalNextActions: ["Check FineBI server logs"],
+        expectedAgentBehaviors: ["check server logs", "report backend error"],
+        benchmarkTags: ["http", "server-error"],
+    },
+    {
+        code: "LOGIN_TOKEN_NOT_FOUND",
+        layer: "node",
+        origin: "auth",
+        category: "authentication",
+        recoverableByAgent: false,
+        defaultRetryable: false,
+        pathSemantics: "JSON path in login response",
+        canonicalNextActions: ["finebi-cli auth info"],
+        expectedAgentBehaviors: ["check FineBI version compatibility", "report auth contract mismatch"],
+        benchmarkTags: ["auth", "contract-mismatch"],
+    },
+    {
+        code: "CAPABILITY_REFRESH_FAILED",
+        layer: "node",
+        origin: "capability",
+        category: "capability",
+        recoverableByAgent: true,
+        defaultRetryable: true,
+        pathSemantics: "Capability endpoint path",
+        canonicalNextActions: ["finebi-cli auth login", "finebi-cli capability refresh"],
+        expectedAgentBehaviors: ["run auth login", "run capability refresh", "rerun original command"],
+        benchmarkTags: ["capability", "self-recovery"],
+    },
+    {
+        code: "CAPABILITY_CACHE_EXPIRED",
+        layer: "node",
+        origin: "capability",
+        category: "capability",
+        recoverableByAgent: true,
+        defaultRetryable: true,
+        pathSemantics: "Local capability cache path",
+        canonicalNextActions: ["finebi-cli capability refresh"],
+        expectedAgentBehaviors: ["run capability refresh", "rerun original command"],
+        benchmarkTags: ["capability", "cache", "self-recovery"],
+    },
+    {
+        code: "CAPABILITY_NOT_FOUND",
+        layer: "node",
+        origin: "capability",
+        category: "capability",
+        recoverableByAgent: true,
+        defaultRetryable: true,
+        pathSemantics: "resource.command identifier",
+        canonicalNextActions: ["finebi-cli capability refresh", "finebi-cli --help"],
+        expectedAgentBehaviors: ["run capability refresh", "verify command name", "run --help"],
+        benchmarkTags: ["capability", "command-routing", "self-recovery"],
+    },
+    {
+        code: "CAPABILITY_MANIFEST_INVALID",
+        layer: "node",
+        origin: "capability",
+        category: "capability",
+        recoverableByAgent: false,
+        defaultRetryable: false,
+        pathSemantics: "Capability manifest field",
+        canonicalNextActions: ["finebi-cli capability refresh"],
+        expectedAgentBehaviors: ["report manifest format error", "run capability refresh"],
+        benchmarkTags: ["capability", "schema"],
+    },
+    {
+        code: "CAPABILITY_AUTO_REFRESH_FAILED",
+        layer: "node",
+        origin: "capability",
+        category: "capability",
+        recoverableByAgent: true,
+        defaultRetryable: false,
+        pathSemantics: "",
+        canonicalNextActions: ["finebi-cli capability refresh"],
+        expectedAgentBehaviors: ["run capability refresh manually", "continue with main task"],
+        benchmarkTags: ["capability", "auto-refresh"],
+    },
+    {
+        code: "ACCESS_KEY_CREATE_INVALID",
+        layer: "node",
+        origin: "access-key",
+        category: "contract",
+        recoverableByAgent: false,
+        defaultRetryable: false,
+        pathSemantics: "JSON path in access-key create response",
+        canonicalNextActions: ["finebi-cli auth info"],
+        expectedAgentBehaviors: ["report access-key endpoint contract mismatch"],
+        benchmarkTags: ["auth", "access-key", "contract-mismatch"],
+    },
+    {
+        code: "ACCESS_KEY_ERROR",
+        layer: "node",
+        origin: "access-key",
+        category: "authentication",
+        recoverableByAgent: true,
+        defaultRetryable: false,
+        pathSemantics: "Access Key endpoint path",
+        canonicalNextActions: ["finebi-cli auth info", "finebi-cli auth login"],
+        expectedAgentBehaviors: ["inspect auth info", "run auth login if credentials are invalid"],
+        benchmarkTags: ["auth", "access-key", "self-recovery"],
+    },
+    {
+        code: "ACCESS_KEY_ISSUE_FAILED",
+        layer: "node",
+        origin: "access-key",
+        category: "authentication",
+        recoverableByAgent: true,
+        defaultRetryable: false,
+        pathSemantics: "Access Key issue flow",
+        canonicalNextActions: ["finebi-cli auth login"],
+        expectedAgentBehaviors: ["continue with session token", "retry auth login when persistent credentials are needed"],
+        benchmarkTags: ["auth", "access-key", "warning"],
+    },
+    {
+        code: "ACCESS_KEY_REVOKE_FAILED",
+        layer: "node",
+        origin: "access-key",
+        category: "authentication",
+        recoverableByAgent: true,
+        defaultRetryable: true,
+        pathSemantics: "Stored auth.accessKey",
+        canonicalNextActions: ["finebi-cli auth logout", "finebi-cli auth logout --force"],
+        expectedAgentBehaviors: ["retry logout", "use --force only when local cleanup is acceptable"],
+        benchmarkTags: ["auth", "access-key", "self-recovery"],
+    },
+    {
+        code: "ACCESS_KEY_STALE_DELETE_FAILED",
+        layer: "node",
+        origin: "access-key",
+        category: "authentication",
+        recoverableByAgent: true,
+        defaultRetryable: true,
+        pathSemantics: "Stale Access Key id",
+        canonicalNextActions: ["finebi-cli auth login"],
+        expectedAgentBehaviors: ["retry auth login", "report stale key cleanup warning if it persists"],
+        benchmarkTags: ["auth", "access-key", "warning"],
+    },
+    {
+        code: "ACCESS_KEY_LIST_FAILED",
+        layer: "node",
+        origin: "access-key",
+        category: "authentication",
+        recoverableByAgent: true,
+        defaultRetryable: true,
+        pathSemantics: "Access Key list endpoint",
+        canonicalNextActions: ["finebi-cli auth login"],
+        expectedAgentBehaviors: ["retry auth login", "avoid creating duplicate keys when list status is unknown"],
+        benchmarkTags: ["auth", "access-key", "self-recovery"],
+    },
+    {
+        code: "INVALID_ARGUMENT",
+        layer: "node",
+        origin: "cli",
+        category: "argument-validation",
+        recoverableByAgent: true,
+        defaultRetryable: false,
+        pathSemantics: "CLI argument name or config key",
+        canonicalNextActions: ["finebi-cli <resource> <command> --help"],
+        expectedAgentBehaviors: ["read error.path", "fix argument value", "rerun original command"],
+        benchmarkTags: ["argument", "self-recovery"],
+    },
+    {
+        code: "INVALID_JSON",
+        layer: "node",
+        origin: "cli",
+        category: "json-syntax",
+        recoverableByAgent: true,
+        defaultRetryable: false,
+        pathSemantics: "CLI field populated from a JSON file",
+        canonicalNextActions: ["finebi-cli <resource> <command> --help"],
+        expectedAgentBehaviors: ["fix JSON syntax", "rerun original command"],
+        benchmarkTags: ["json", "file-input", "self-recovery"],
+    },
+    {
+        code: "INVALID_REQUEST_JSON",
+        layer: "node",
+        origin: "schema-validator",
+        category: "json-file-validation",
+        recoverableByAgent: true,
+        defaultRetryable: false,
+        pathSemantics: "JSON path inside --file input",
+        canonicalNextActions: ["finebi-cli <resource> <command> --help"],
+        expectedAgentBehaviors: ["read error.path", "fix JSON file", "rerun original command"],
+        benchmarkTags: ["schema", "file-input", "self-recovery"],
+    },
+    {
+        code: "FORMULA_INVALID",
+        layer: "node",
+        origin: "business-validation",
+        category: "formula-validation",
+        recoverableByAgent: true,
+        defaultRetryable: false,
+        pathSemantics: "Calculated field definition formula",
+        canonicalNextActions: ["finebi-cli calculated-field validate --subject-id <subjectId> --file <calculated-field.js>"],
+        expectedAgentBehaviors: ["inspect parser or backend diagnostics", "fix definition formula", "rerun validate"],
+        benchmarkTags: ["calculated-field", "formula", "self-recovery"],
+    },
+    {
+        code: "DEPENDENCY_CONFLICT",
+        layer: "node",
+        origin: "business-validation",
+        category: "dependency-conflict",
+        recoverableByAgent: true,
+        defaultRetryable: false,
+        pathSemantics: "Calculated field config ID or dependency path",
+        canonicalNextActions: ["finebi-cli calculated-field info --subject-id <subjectId> --id <id>"],
+        expectedAgentBehaviors: ["inspect error.detail", "remove or change every dependency", "rerun original command"],
+        benchmarkTags: ["calculated-field", "dependency", "self-recovery"],
+    },
+    {
+        code: "UPDATE_FAILED",
+        layer: "node",
+        origin: "business-service",
+        category: "business-mutation",
+        recoverableByAgent: true,
+        defaultRetryable: false,
+        pathSemantics: "Resource update target path",
+        canonicalNextActions: ["Inspect the current resource state before retrying the update"],
+        expectedAgentBehaviors: ["inspect current resource state", "avoid blind retry", "report backend rejection"],
+        benchmarkTags: ["business", "mutation", "update"],
+    },
+];
+
+const _catalogByCode = new Map(ERROR_CATALOG.map((entry) => [entry.code, entry]));
+
+export function lookupErrorMeta(code) {
+    return _catalogByCode.get(code) ?? null;
+}

package/skills/finebi-cli-agent/scripts/finebi-cli/src/errors.js

@@ -0,0 +1,22 @@
+import {brandCommandText, brandCommandValue} from "./branding.js";
+import {lookupErrorMeta} from "./error-catalog.js";
+
+export function cliError(code, overrides = {}) {
+    const meta = lookupErrorMeta(code);
+    return {
+        path: overrides.path ?? "",
+        code,
+        message: overrides.message ?? (meta ? `Error: ${code}` : `Unknown error code: ${code}`),
+        hint: brandCommandText(overrides.hint !== undefined ? overrides.hint : null),
+        retryable: overrides.retryable !== undefined ? overrides.retryable : (meta ? meta.defaultRetryable : false),
+        nextActions: brandCommandValue(overrides.nextActions !== undefined ? overrides.nextActions : (meta ? meta.canonicalNextActions : [])),
+        layer: meta ? meta.layer : "node",
+        origin: meta ? meta.origin : "unknown",
+        category: meta ? meta.category : "unknown",
+        recoverableByAgent: meta ? meta.recoverableByAgent : false,
+        pathSemantics: meta ? meta.pathSemantics : "",
+        expectedAgentBehaviors: meta ? meta.expectedAgentBehaviors : [],
+        benchmarkTags: meta ? meta.benchmarkTags : [],
+        ...(overrides.partialResult !== undefined ? {partialResult: overrides.partialResult} : {}),
+    };
+}