@aexol/spectral 0.9.55 → 0.9.59

package/dist/extensions/kanban-bridge.js

@@ -43,11 +43,32 @@ async function graphqlRequest(opts, query, variables) {
         catch { /* ignore */ }
         throw new GraphQLError(`HTTP ${res.status} from GraphQL${detail ? `: ${detail}` : ""}`, res.status);
     }
-    const json = (await res.json());
+    const rawBody = await res.text();
+    let json;
+    try {
+        json = JSON.parse(rawBody);
+    }
+    catch {
+        throw new GraphQLError(`GraphQL returned non-JSON response (${res.status}): ${rawBody.slice(0, 200)}`);
+    }
     if (json.errors && json.errors.length > 0) {
-        throw new GraphQLError(json.errors.map((e) => e.message).join("; "));
+        const errDetail = json.errors.map((e) => {
+            let s = e.message;
+            if (e.extensions?.code)
+                s += ` [code: ${e.extensions.code}]`;
+            return s;
+        }).join("; ");
+        // Detect auth-related errors — the backend returns 200 with auth errors in the body
+        const isAuthError = json.errors.some((e) => e.extensions?.code === "UNAUTHENTICATED" ||
+            (e.extensions?.originalError &&
+                typeof e.extensions.originalError === "object" &&
+                e.extensions.originalError.message === "Authentication required"));
+        process.stderr.write(`[kanban-bridge] GraphQL errors from ${opts.backendUrl}/graphql (project ${opts.projectId}): ${errDetail}\n`);
+        process.stderr.write(`[kanban-bridge] Full response: ${rawBody.slice(0, 500)}\n`);
+        throw new GraphQLError(errDetail, isAuthError ? 401 : undefined);
     }
     if (!json.data) {
+        process.stderr.write(`[kanban-bridge] GraphQL missing data from ${opts.backendUrl}/graphql (project ${opts.projectId}): ${rawBody.slice(0, 500)}\n`);
         throw new GraphQLError("GraphQL response missing data");
     }
     return json.data;
@@ -164,14 +185,42 @@ async function deleteKanbanTask(opts, taskId) {
 // ---------------------------------------------------------------------------
 // Config resolution
 // ---------------------------------------------------------------------------
-import { readConfig } from "../config.js";
+import { getApiUrl, getConfigFile, readConfig } from "../config.js";
 import { readStudioBinding } from "../studio-binding.js";
-import { getConfigFile } from "../config.js";
-import { ensureAuthenticated } from "../auth-helper.js";
+import { ensureAuthenticated, runOAuthFlow } from "../auth-helper.js";
+import { stat } from "node:fs/promises";
+import { join } from "node:path";
 // Track whether we've already attempted reauth in this session to avoid loops
 let _reauthAttempted = false;
-let _studioBinding = null;
-async function resolveKanbanConfig(explicitProjectId) {
+const _bindingCache = new Map();
+async function refreshBindingForCwd(cwd) {
+    const bindingFile = join(cwd, ".aexol", "aexol.jsonc");
+    const cached = _bindingCache.get(cwd);
+    let mtimeMs;
+    try {
+        mtimeMs = (await stat(bindingFile)).mtimeMs;
+    }
+    catch (err) {
+        const code = err.code;
+        if (code === "ENOENT" || code === "ENOTDIR") {
+            _bindingCache.set(cwd, { binding: null, mtimeMs: null });
+            return null;
+        }
+        return cached?.binding ?? null;
+    }
+    if (cached && mtimeMs === cached.mtimeMs)
+        return cached.binding;
+    try {
+        const binding = await readStudioBinding(cwd);
+        _bindingCache.set(cwd, { binding, mtimeMs });
+        return binding;
+    }
+    catch {
+        _bindingCache.set(cwd, { binding: cached?.binding ?? null, mtimeMs: null });
+        return cached?.binding ?? null;
+    }
+}
+async function resolveKanbanConfig(explicitProjectId, cwd) {
     const cfg = await readConfig();
     if (!cfg) {
         if (!_reauthAttempted) {
@@ -179,42 +228,50 @@ async function resolveKanbanConfig(explicitProjectId) {
             process.stderr.write(`[kanban-bridge] No config found at ${getConfigFile()}. Attempting OAuth login...\n`);
             const result = await ensureAuthenticated();
             if (result.ok && result.config) {
-                return resolveKanbanConfig(explicitProjectId); // Retry with fresh config
+                return resolveKanbanConfig(explicitProjectId, cwd); // Retry with fresh config
             }
         }
         process.stderr.write(`[kanban-bridge] No config found at ${getConfigFile()}. Run \`spectral login\`.\n`);
         return null;
     }
-    const token = cfg.teamApiKey || cfg.userJwt || "";
+    // If we only have a team API key, proactively get a user JWT via OAuth.
+    // The team API key passes MCP health checks but fails GraphQL kanban auth.
+    if (cfg.teamApiKey && !cfg.userJwt && !_reauthAttempted) {
+        _reauthAttempted = true;
+        process.stderr.write(`[kanban-bridge] Team API key found but no user JWT. Kanban requires user auth — obtaining via OAuth...\n`);
+        const oauthResult = await runOAuthFlow();
+        if (oauthResult.ok) {
+            return resolveKanbanConfig(explicitProjectId, cwd); // Retry with fresh config (now has userJwt)
+        }
+        process.stderr.write(`[kanban-bridge] OAuth failed: ${oauthResult.reason}. Kanban calls will likely fail.\n`);
+    }
+    const token = cfg.userJwt || cfg.teamApiKey || "";
     if (!token) {
         if (!_reauthAttempted) {
             _reauthAttempted = true;
             process.stderr.write(`[kanban-bridge] No auth token in config. Attempting OAuth login...\n`);
             const result = await ensureAuthenticated();
             if (result.ok && result.config) {
-                return resolveKanbanConfig(explicitProjectId);
+                return resolveKanbanConfig(explicitProjectId, cwd);
             }
         }
         process.stderr.write(`[kanban-bridge] No auth token in config. Run \`spectral login\`.\n`);
         return null;
     }
     // Resolve backend URL — the config stores the MCP URL, we need the base
-    const backendUrl = cfg.apiUrl.replace(/\/mcp$/, "");
+    const backendUrl = process.env.SPECTRAL_BACKEND_URL ||
+        getApiUrl(cfg.apiUrl).replace(/\/mcp\/?$/, "");
     // Resolve projectId: explicit param > studio binding
     let projectId = explicitProjectId || null;
     if (!projectId) {
-        try {
-            const binding = _studioBinding ?? await readStudioBinding();
-            if (binding?.projectId) {
-                projectId = binding.projectId;
-            }
-        }
-        catch {
-            // ignore
+        const lookupCwd = cwd ?? process.cwd();
+        const binding = await refreshBindingForCwd(lookupCwd);
+        if (binding?.projectId) {
+            projectId = binding.projectId;
         }
     }
     if (!projectId) {
-        process.stderr.write(`[kanban-bridge] No projectId available. Bind a project via \`spectral bind <project-id>\` or pass projectId explicitly.\n`);
+        process.stderr.write(`[kanban-bridge] No projectId available for cwd ${cwd ?? process.cwd()}. Bind a project via \`spectral bind <project-id>\` or pass projectId explicitly.\n`);
         return null;
     }
     return { token, backendUrl, projectId };
@@ -290,7 +347,12 @@ const kanbanListTool = {
             };
         }
         catch (err) {
+            if (err instanceof GraphQLError && (err.status === 401 || err.status === 403)) {
+                throw err; // Propagate to withReauthRetry for OAuth handling
+            }
             const msg = err instanceof Error ? err.message : String(err);
+            process.stderr.write(`[kanban-bridge] kanban_list failed for project ${cfg.projectId}: ${msg}\n` +
+                `${err instanceof Error && err.stack ? err.stack + '\n' : ''}`);
             return {
                 content: [{ type: "text", text: `Error listing tasks: ${msg}` }],
                 details: { isError: true },
@@ -347,7 +409,12 @@ const kanbanGetTool = {
             };
         }
         catch (err) {
+            if (err instanceof GraphQLError && (err.status === 401 || err.status === 403)) {
+                throw err; // Propagate to withReauthRetry for OAuth handling
+            }
             const msg = err instanceof Error ? err.message : String(err);
+            process.stderr.write(`[kanban-bridge] kanban_get failed for project ${cfg.projectId}: ${msg}\n` +
+                `${err instanceof Error && err.stack ? err.stack + '\n' : ''}`);
             return { content: [{ type: "text", text: `Error: ${msg}` }], details: { isError: true } };
         }
     },
@@ -394,7 +461,12 @@ const kanbanCreateTool = {
             };
         }
         catch (err) {
+            if (err instanceof GraphQLError && (err.status === 401 || err.status === 403)) {
+                throw err; // Propagate to withReauthRetry for OAuth handling
+            }
             const msg = err instanceof Error ? err.message : String(err);
+            process.stderr.write(`[kanban-bridge] kanban_create failed for project ${cfg.projectId}: ${msg}\n` +
+                `${err instanceof Error && err.stack ? err.stack + '\n' : ''}`);
             return { content: [{ type: "text", text: `Error creating task: ${msg}` }], details: { isError: true } };
         }
     },
@@ -444,7 +516,12 @@ const kanbanUpdateTool = {
             };
         }
         catch (err) {
+            if (err instanceof GraphQLError && (err.status === 401 || err.status === 403)) {
+                throw err; // Propagate to withReauthRetry for OAuth handling
+            }
             const msg = err instanceof Error ? err.message : String(err);
+            process.stderr.write(`[kanban-bridge] kanban_update failed for project ${cfg.projectId}: ${msg}\n` +
+                `${err instanceof Error && err.stack ? err.stack + '\n' : ''}`);
             return { content: [{ type: "text", text: `Error updating task: ${msg}` }], details: { isError: true } };
         }
     },
@@ -495,7 +572,12 @@ const kanbanMoveTool = {
             };
         }
         catch (err) {
+            if (err instanceof GraphQLError && (err.status === 401 || err.status === 403)) {
+                throw err; // Propagate to withReauthRetry for OAuth handling
+            }
             const msg = err instanceof Error ? err.message : String(err);
+            process.stderr.write(`[kanban-bridge] kanban_move failed for project ${cfg.projectId}: ${msg}\n` +
+                `${err instanceof Error && err.stack ? err.stack + '\n' : ''}`);
             return { content: [{ type: "text", text: `Error moving task: ${msg}` }], details: { isError: true } };
         }
     },
@@ -616,7 +698,12 @@ const kanbanNextTool = {
             return { content: [{ type: "text", text: lines.join("\n") }], details: {} };
         }
         catch (err) {
+            if (err instanceof GraphQLError && (err.status === 401 || err.status === 403)) {
+                throw err; // Propagate to withReauthRetry for OAuth handling
+            }
             const msg = err instanceof Error ? err.message : String(err);
+            process.stderr.write(`[kanban-bridge] kanban_next failed for project ${cfg.projectId}: ${msg}\n` +
+                `${err instanceof Error && err.stack ? err.stack + '\n' : ''}`);
             return { content: [{ type: "text", text: `Error: ${msg}` }], details: { isError: true } };
         }
     },
@@ -650,7 +737,12 @@ const kanbanDeleteTool = {
             };
         }
         catch (err) {
+            if (err instanceof GraphQLError && (err.status === 401 || err.status === 403)) {
+                throw err; // Propagate to withReauthRetry for OAuth handling
+            }
             const msg = err instanceof Error ? err.message : String(err);
+            process.stderr.write(`[kanban-bridge] kanban_delete failed for project ${cfg.projectId}: ${msg}\n` +
+                `${err instanceof Error && err.stack ? err.stack + '\n' : ''}`);
             return { content: [{ type: "text", text: `Error deleting task: ${msg}` }], details: { isError: true } };
         }
     },
@@ -671,15 +763,17 @@ function withReauthRetry(toolName, execute) {
             if (err instanceof GraphQLError && (err.status === 401 || err.status === 403)) {
                 if (_reauthAttempted) {
                     return {
-                        content: [{ type: "text", text: `Authentication failed (HTTP ${err.status}). Please run \`spectral login\` to re-authenticate.` }],
+                        content: [{ type: "text", text: `Error: Authentication failed (HTTP ${err.status}). Please run \`spectral login\` to re-authenticate.` }],
                         details: { isError: true },
                     };
                 }
                 _reauthAttempted = true;
                 process.stderr.write(`[kanban-bridge] Auth error (${err.status}) on ${toolName}. Attempting OAuth re-login...\n`);
-                const result = await ensureAuthenticated();
-                if (result.ok && result.config) {
+                const oauthResult = await runOAuthFlow();
+                if (oauthResult.ok) {
                     process.stderr.write(`[kanban-bridge] Re-authenticated — retrying ${toolName}...\n`);
+                    // Reset reauth flag so resolveKanbanConfig can use the fresh token
+                    _reauthAttempted = false;
                     try {
                         return await execute(toolCallId, params, signal, onUpdate, ctx);
                     }
@@ -692,11 +786,17 @@ function withReauthRetry(toolName, execute) {
                     }
                 }
                 return {
-                    content: [{ type: "text", text: `Re-authentication failed: ${result.reason ?? "unknown"}. Please run \`spectral login\` manually.` }],
+                    content: [{ type: "text", text: `Error: Re-authentication failed: ${oauthResult.reason ?? "unknown"}. Please run \`spectral login\` manually.` }],
                     details: { isError: true },
                 };
             }
-            throw err;
+            const msg = err instanceof Error ? err.message : String(err);
+            process.stderr.write(`[kanban-bridge] ${toolName} unexpected failure: ${msg}\n` +
+                `${err instanceof Error && err.stack ? err.stack + "\n" : ""}`);
+            return {
+                content: [{ type: "text", text: `Kanban ${toolName} failed: ${msg}` }],
+                details: { isError: true },
+            };
         }
     };
 }
@@ -727,8 +827,7 @@ export default async function kanbanBridgeExtension(ext) {
     }
     // Verify config is resolvable on startup (non-fatal — tools work lazily too)
     ext.on("session_start", async (_event, ctx) => {
-        _studioBinding = await readStudioBinding(ctx.cwd);
-        const cfg = await resolveKanbanConfig();
+        const cfg = await resolveKanbanConfig(undefined, ctx.cwd);
         if (cfg) {
             process.stderr.write(`[kanban-bridge] Registered ${registered} Kanban tool(s). Connected to project ${cfg.projectId}.\n`);
         }

package/dist/extensions/web/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Web Fetch native extension for Spectral.
+ *
+ * Registers a single tool, `web_fetch`, which fetches a public URL and returns
+ * its content as text, markdown, or raw HTML. The model provides URLs itself;
+ * there is no search capability.
+ */
+import type { ExtensionAPI } from "../../sdk/coding-agent/index.js";
+export default function webExtension(ext: ExtensionAPI): Promise<void>;
+//# sourceMappingURL=index.d.ts.map

package/dist/extensions/web/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/extensions/web/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,iCAAiC,CAAC;AAGpE,wBAA8B,YAAY,CAAC,GAAG,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CAQ3E"}

package/dist/extensions/web/index.js

@@ -0,0 +1,11 @@
+import { registerWebFetchTool } from "./tools/fetch.js";
+export default async function webExtension(ext) {
+    try {
+        registerWebFetchTool(ext);
+        process.stderr.write("[web] Registered web_fetch tool.\n");
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        process.stderr.write(`[web] Failed to register web_fetch tool: ${msg}\n`);
+    }
+}

package/dist/extensions/web/tools/fetch.d.ts

@@ -0,0 +1,3 @@
+import type { ExtensionAPI } from "../../../sdk/coding-agent/index.js";
+export declare function registerWebFetchTool(ext: ExtensionAPI): void;
+//# sourceMappingURL=fetch.d.ts.map

package/dist/extensions/web/tools/fetch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fetch.d.ts","sourceRoot":"","sources":["../../../../src/extensions/web/tools/fetch.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAmB,YAAY,EAAkB,MAAM,oCAAoC,CAAC;AA+BxG,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,YAAY,GAAG,IAAI,CA2D5D"}

package/dist/extensions/web/tools/fetch.js

@@ -0,0 +1,80 @@
+/**
+ * web_fetch tool definition.
+ */
+import { Type } from "typebox";
+import { truncateTail } from "../../../sdk/coding-agent/core/tools/truncate.js";
+import { fetchWebPage, WebFetchError } from "../utils/fetcher.js";
+import { convertContent } from "../utils/parser.js";
+const MAX_OUTPUT_LINES = 4000;
+const MAX_OUTPUT_BYTES = 200 * 1024; // 200 KB
+const webFetchSchema = Type.Object({
+    url: Type.String({
+        description: "The URL to fetch. Must begin with http:// or https://.",
+        pattern: "^https?://",
+    }),
+    format: Type.Optional(Type.Union([Type.Literal("text"), Type.Literal("markdown"), Type.Literal("html"), Type.Literal("json")], {
+        default: "markdown",
+        description: "Output format: text, markdown (default), html, or json.",
+    })),
+    timeout: Type.Optional(Type.Number({
+        default: 30,
+        minimum: 1,
+        maximum: 120,
+        description: "Request timeout in seconds (default 30, maximum 120).",
+    })),
+});
+export function registerWebFetchTool(ext) {
+    const tool = {
+        name: "web_fetch",
+        label: "Web Fetch",
+        description: "Fetch a public URL and return its content as readable text, markdown, raw HTML, or pretty JSON. " +
+            "Useful for reading documentation, GitHub pages, Reddit JSON endpoints, and other web content. " +
+            "Supports HTTP/HTTPS only and rejects binary content.",
+        promptSnippet: "`web_fetch { url, format?, timeout? }` — fetch a web page as markdown/text/HTML/JSON",
+        parameters: webFetchSchema,
+        async execute(_toolCallId, params, signal, _onUpdate, _ctx) {
+            const { url, format = "markdown", timeout = 30 } = params;
+            try {
+                const fetchResult = await fetchWebPage(url, {
+                    timeoutSeconds: timeout,
+                    signal,
+                });
+                const converted = await convertContent(fetchResult.content, format);
+                const truncation = truncateTail(converted, {
+                    maxLines: MAX_OUTPUT_LINES,
+                    maxBytes: MAX_OUTPUT_BYTES,
+                });
+                const output = truncation.content;
+                const truncationNotice = truncation.truncated
+                    ? `\n\n[Output truncated: exceeded ${truncation.truncatedBy === "bytes" ? `${MAX_OUTPUT_BYTES} bytes` : `${MAX_OUTPUT_LINES} lines`}. Original size: ${truncation.totalBytes} bytes, ${truncation.totalLines} lines.]`
+                    : "";
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: `✓ Fetched ${fetchResult.finalUrl}\nContent-Type: ${fetchResult.contentType || "unknown"}\nFormat: ${format}\nSize: ${fetchResult.contentLengthBytes} bytes${truncationNotice}\n\n${output}`,
+                        },
+                    ],
+                    details: {
+                        isError: false,
+                        url: fetchResult.finalUrl,
+                        contentType: fetchResult.contentType,
+                        format,
+                        output,
+                        truncated: truncation.truncated,
+                        truncatedBy: truncation.truncatedBy,
+                    },
+                };
+            }
+            catch (err) {
+                const reason = err instanceof WebFetchError || err instanceof Error ? err.message : String(err);
+                const message = `Unable to fetch ${url}: ${reason}`;
+                return {
+                    content: [{ type: "text", text: `❌ ${message}` }],
+                    details: { isError: true, message },
+                };
+            }
+        },
+    };
+    ext.registerTool(tool);
+}

package/dist/extensions/web/utils/fetcher.d.ts

@@ -0,0 +1,34 @@
+export declare class WebFetchError extends Error {
+    constructor(message: string);
+}
+export interface WebFetchOptions {
+    timeoutSeconds?: number;
+    signal?: AbortSignal;
+    userAgent?: string;
+    /**
+     * Bypass SSRF private-host/IP blocking. Used only by tests that spin up a
+     * local mock HTTP server; never exposed through the `web_fetch` tool schema.
+     */
+    allowPrivateHosts?: boolean;
+}
+export interface WebFetchResult {
+    url: string;
+    finalUrl: string;
+    contentType: string;
+    content: string;
+    contentLengthBytes: number;
+}
+/**
+ * Validate a URL with SSRF protection.
+ *
+ * Throws WebFetchError for invalid URLs, non-http(s) protocols, blocked
+ * hostnames, or hostnames that resolve to private IP addresses.
+ */
+export declare function validateUrl(urlStr: string, allowPrivateHosts?: boolean): Promise<URL>;
+/** Validate that the Content-Type is readable text, not binary media. */
+export declare function validateContentType(contentType: string): void;
+/**
+ * Fetch a public URL and return its decoded text content.
+ */
+export declare function fetchWebPage(url: string, opts?: WebFetchOptions): Promise<WebFetchResult>;
+//# sourceMappingURL=fetcher.d.ts.map

package/dist/extensions/web/utils/fetcher.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fetcher.d.ts","sourceRoot":"","sources":["../../../../src/extensions/web/utils/fetcher.ts"],"names":[],"mappings":"AASA,qBAAa,aAAc,SAAQ,KAAK;gBAC1B,OAAO,EAAE,MAAM;CAI5B;AAED,MAAM,WAAW,eAAe;IAC9B,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;OAGG;IACH,iBAAiB,CAAC,EAAE,OAAO,CAAC;CAC7B;AAED,MAAM,WAAW,cAAc;IAC7B,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC;IAChB,kBAAkB,EAAE,MAAM,CAAC;CAC5B;AAuDD;;;;;GAKG;AACH,wBAAsB,WAAW,CAC/B,MAAM,EAAE,MAAM,EACd,iBAAiB,UAAQ,GACxB,OAAO,CAAC,GAAG,CAAC,CAoDd;AAcD,yEAAyE;AACzE,wBAAgB,mBAAmB,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI,CA+C7D;AAED;;GAEG;AACH,wBAAsB,YAAY,CAChC,GAAG,EAAE,MAAM,EACX,IAAI,GAAE,eAAoB,GACzB,OAAO,CAAC,cAAc,CAAC,CAoIzB"}