npm - @aexol/spectral - Versions diffs - 0.2.13 → 0.2.15 - Mend

@aexol/spectral 0.2.13 → 0.2.15

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.

Files changed (5) hide show

package/dist/commands/login-oauth.js +14 -10
package/dist/config.js +15 -10
package/dist/extensions/aexol-mcp.js +206 -3
package/dist/server/handlers/paths-autocomplete.js +56 -27
package/package.json +1 -1

package/dist/commands/login-oauth.js CHANGED Viewed

@@ -18,11 +18,11 @@ const DEFAULT_BACKEND_URL = "https://studio.aexol.ai";
 const CALLBACK_TIMEOUT_MS = 120_000; // 2 minutes
 /**
  * Start a temporary HTTP server to receive the OAuth callback.
- * Returns the port and a promise that resolves with the JWT token.
+ * Returns the server and a promise that resolves with the JWT token.
  */
 function listenForCallback(timeoutMs) {
-    return new Promise((resolve, reject) => {
-        const server = createServer();
+    const server = createServer();
+    const tokenPromise = new Promise((resolve, reject) => {
         const timeout = setTimeout(() => {
             server.close();
             reject(new Error(`Timed out after ${timeoutMs / 1000}s waiting for browser authorization.`));
@@ -34,7 +34,7 @@ function listenForCallback(timeoutMs) {
                 clearTimeout(timeout);
                 res.writeHead(200, { "Content-Type": "text/html; charset=utf-8" });
                 res.end("<html><body><h1>✓ Authorized</h1><p>You can close this tab and return to your terminal.</p></body></html>");
-                resolve({ token, server });
+                resolve(token);
             }
             else {
                 res.writeHead(400, { "Content-Type": "text/plain" });
@@ -46,10 +46,8 @@ function listenForCallback(timeoutMs) {
             server.close();
             reject(new Error(`Failed to start local server: ${err.message}`));
         });
-        server.listen(0, "127.0.0.1", () => {
-            // Port 0 lets the OS assign an ephemeral port — we read it from the server.
-        });
     });
+    return { server, tokenPromise };
 }
 /** Derive the landing base URL from the backend URL. */
 function deriveLandingUrl(backendUrl) {
@@ -72,8 +70,14 @@ export async function runLoginOAuth() {
     let server;
     let token;
     try {
-        const result = await listenForCallback(CALLBACK_TIMEOUT_MS);
-        server = result.server;
+        const { server: srv, tokenPromise } = listenForCallback(CALLBACK_TIMEOUT_MS);
+        server = srv;
+        // Start listening on a random port, then wait for it to be ready
+        server.listen(0, "127.0.0.1");
+        await new Promise((resolve, reject) => {
+            server.once("listening", resolve);
+            server.once("error", reject);
+        });
         const addr = server.address();
         const port = addr.port;
         // Open browser to the CLI auth page
@@ -93,7 +97,7 @@ export async function runLoginOAuth() {
         });
         // Wait for the token
         process.stdout.write(pc.dim("Waiting for authorization...\n"));
-        token = result.token;
+        token = await tokenPromise;
     }
     catch (err) {
         const msg = err instanceof Error ? err.message : String(err);

package/dist/config.js CHANGED Viewed

@@ -56,16 +56,21 @@ export async function readConfig() {
     }
     try {
         const parsed = JSON.parse(raw);
-        if (typeof parsed.apiUrl === "string" &&
-            typeof parsed.teamApiKey === "string" &&
-            parsed.teamApiKey.length > 0) {
-            return {
-                apiUrl: parsed.apiUrl,
-                teamApiKey: parsed.teamApiKey,
-                userJwt: typeof parsed.userJwt === "string" ? parsed.userJwt : undefined,
-            };
-        }
-        return null;
+        if (typeof parsed.apiUrl !== "string")
+            return null;
+        const teamApiKey = typeof parsed.teamApiKey === "string" && parsed.teamApiKey.length > 0
+            ? parsed.teamApiKey
+            : "";
+        const userJwt = typeof parsed.userJwt === "string" && parsed.userJwt.length > 0
+            ? parsed.userJwt
+            : undefined;
+        if (!teamApiKey && !userJwt)
+            return null;
+        return {
+            apiUrl: parsed.apiUrl,
+            teamApiKey,
+            userJwt,
+        };
     }
     catch {
         return null;

package/dist/extensions/aexol-mcp.js CHANGED Viewed

@@ -4,8 +4,13 @@
  * Loaded by the spectral wrapper via `--extension <abs-path>`. On startup it:
  *   1. Reads ~/.spectral/config.json (writen by `spectral login`).
  *   2. Calls tools/list against the MCP backend once.
- *   3. Registers every returned tool through pi.registerTool() so the model
- *      can call them like built-in tools.
+ *   3. Reads the local Studio binding (`.aexol/aexol.jsonc`) so remote tools
+ *      auto-inherit `teamId` / `projectId` without needing `remote_set_context`.
+ *   4. Registers every returned remote tool through pi.registerTool() so the
+ *      model can call them like built-in tools.
+ *   5. Registers local binding-management tools (`local_bind_project`,
+ *      `local_unbind_project`, `local_get_binding`) so users can bind a
+ *      directory to an Aexol Studio project from within the agent.
  *
  * Each registered tool is just a thin proxy: when pi's model invokes it, we
  * translate the call into a JSON-RPC tools/call POST and unwrap the response
@@ -17,6 +22,7 @@
  */
 import { getApiUrl, getConfigFile, readConfig } from "../config.js";
 import { AexolMcpClient, AexolMcpError } from "../mcp-client.js";
+import { readStudioBinding, writeStudioBinding, deleteStudioBinding, } from "../studio-binding.js";
 /**
  * Render a backend tool result into a single string for pi.
  *
@@ -54,6 +60,27 @@ function toLabel(name) {
         .map((w) => w.charAt(0).toUpperCase() + w.slice(1))
         .join(" ") || name;
 }
+// ---------------------------------------------------------------------------
+// Studio binding – in-memory cache, refreshed on startup & by local tools
+// ---------------------------------------------------------------------------
+let currentBinding = null;
+/**
+ * Augment tool-call params with `teamId` and `projectId` from the current
+ * Studio binding when they are not already set by the model. Only applies
+ * to remote tools (names that start with `remote_`).
+ */
+function augmentParams(toolName, params) {
+    if (!currentBinding || !toolName.startsWith("remote_"))
+        return params;
+    const augmented = { ...params };
+    if (currentBinding.teamId && !("teamId" in params)) {
+        augmented.teamId = currentBinding.teamId;
+    }
+    if (currentBinding.projectId && !("projectId" in params)) {
+        augmented.projectId = currentBinding.projectId;
+    }
+    return augmented;
+}
 export default async function aexolMcpExtension(pi) {
     const cfg = await readConfig();
     if (!cfg) {
@@ -63,6 +90,21 @@ export default async function aexolMcpExtension(pi) {
     }
     const apiUrl = getApiUrl(cfg.apiUrl);
     const client = new AexolMcpClient(apiUrl, cfg.teamApiKey);
+    // ---- Load local Studio binding -------------------------------------------
+    try {
+        currentBinding = await readStudioBinding();
+        if (currentBinding) {
+            const displayName = currentBinding.name ?? currentBinding.projectId;
+            process.stderr.write(`[aexol-mcp] Studio binding found: ${displayName} (${currentBinding.projectId})` +
+                (currentBinding.teamId ? `, team ${currentBinding.teamId}` : "") +
+                `\n`);
+        }
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        process.stderr.write(`[aexol-mcp] Failed to read Studio binding: ${msg}\n`);
+        // Non-fatal — remote tools still work with explicit teamId/projectId.
+    }
     let tools;
     try {
         tools = await client.listTools();
@@ -84,7 +126,8 @@ export default async function aexolMcpExtension(pi) {
             description: tool.description ?? "",
             parameters,
             async execute(_toolCallId, params) {
-                const res = await client.callTool(tool.name, params);
+                const augmented = augmentParams(tool.name, params);
+                const res = await client.callTool(tool.name, augmented);
                 const text = renderContentToString(res.content);
                 if (res.isError === true) {
                     // Surface backend tool errors as a textual result, not a thrown
@@ -113,5 +156,165 @@ export default async function aexolMcpExtension(pi) {
             process.stderr.write(`[aexol-mcp] Failed to register tool "${tool.name}": ${msg}\n`);
         }
     }
+    // ---- Register local binding-management tools -----------------------------
+    // These allow the model to bind / unbind / inspect the Studio project
+    // binding directly from within the agent, without the user having to drop
+    // out to the terminal and run `spectral bind` / `spectral unbind`.
+    try {
+        pi.registerTool({
+            name: "local_bind_project",
+            label: "Bind Project",
+            description: "Link the current working directory to an Aexol Studio project. " +
+                "After binding, all remote_* tools will automatically use this project context " +
+                "(no need to set teamId/projectId on every call). " +
+                "Use this when you want to work within a specific Aexol Studio project.",
+            parameters: {
+                type: "object",
+                properties: {
+                    projectId: {
+                        type: "string",
+                        description: "The Aexol Studio project ID to bind to (required). Copy this from the project URL in Studio.",
+                    },
+                    teamId: {
+                        type: "string",
+                        description: "Optional team ID. If omitted, remote tools use only the projectId for context.",
+                    },
+                    name: {
+                        type: "string",
+                        description: "Optional human-readable name for the binding (shown in logs and status messages).",
+                    },
+                },
+                required: ["projectId"],
+            },
+            async execute(_toolCallId, params) {
+                const p = params;
+                if (!p.projectId || typeof p.projectId !== "string") {
+                    return {
+                        content: [{ type: "text", text: "Error: projectId (string) is required." }],
+                        details: { isError: true },
+                    };
+                }
+                const binding = {
+                    projectId: p.projectId,
+                    ...(p.teamId ? { teamId: p.teamId } : {}),
+                    ...(p.name ? { name: p.name } : {}),
+                };
+                try {
+                    await writeStudioBinding(binding);
+                    currentBinding = binding;
+                    const displayName = binding.name ?? binding.projectId;
+                    return {
+                        content: [{
+                                type: "text",
+                                text: `✓ Bound to Studio project: ${displayName} (${binding.projectId})` +
+                                    (binding.teamId ? `, team ${binding.teamId}` : "") +
+                                    `\nAll remote_* tools will now use this project context by default.`,
+                            }],
+                        details: { isError: false },
+                    };
+                }
+                catch (err) {
+                    const msg = err instanceof Error ? err.message : String(err);
+                    return {
+                        content: [{ type: "text", text: `Error writing binding: ${msg}` }],
+                        details: { isError: true },
+                    };
+                }
+            },
+        });
+        registered++;
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        process.stderr.write(`[aexol-mcp] Failed to register local_bind_project: ${msg}\n`);
+    }
+    try {
+        pi.registerTool({
+            name: "local_unbind_project",
+            label: "Unbind Project",
+            description: "Remove the Aexol Studio project binding from the current working directory. " +
+                "After unbinding, remote_* tools will no longer receive automatic project context " +
+                "— you must pass teamId/projectId explicitly or use local_bind_project to re-bind.",
+            parameters: {
+                type: "object",
+                properties: {},
+            },
+            async execute() {
+                if (!currentBinding) {
+                    return {
+                        content: [{ type: "text", text: "No Studio binding found in this directory — nothing to unbind." }],
+                        details: { isError: false },
+                    };
+                }
+                const displayName = currentBinding.name ?? currentBinding.projectId;
+                const projectId = currentBinding.projectId;
+                try {
+                    const deleted = await deleteStudioBinding();
+                    currentBinding = null;
+                    if (deleted) {
+                        return {
+                            content: [{
+                                    type: "text",
+                                    text: `✓ Unbound from Studio project: ${displayName} (${projectId}).`,
+                                }],
+                            details: { isError: false },
+                        };
+                    }
+                    return {
+                        content: [{ type: "text", text: "Binding file was already removed." }],
+                        details: { isError: false },
+                    };
+                }
+                catch (err) {
+                    const msg = err instanceof Error ? err.message : String(err);
+                    return {
+                        content: [{ type: "text", text: `Error removing binding: ${msg}` }],
+                        details: { isError: true },
+                    };
+                }
+            },
+        });
+        registered++;
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        process.stderr.write(`[aexol-mcp] Failed to register local_unbind_project: ${msg}\n`);
+    }
+    try {
+        pi.registerTool({
+            name: "local_get_binding",
+            label: "Get Binding",
+            description: "Show the current Aexol Studio project binding for this directory. " +
+                "Returns the bound projectId, teamId, and name (if set), or reports that no binding exists.",
+            parameters: {
+                type: "object",
+                properties: {},
+            },
+            async execute() {
+                if (!currentBinding) {
+                    return {
+                        content: [{
+                                type: "text",
+                                text: "No Aexol Studio binding found in this directory.\n" +
+                                    "Use local_bind_project to create one, or `spectral bind <project-id>` from the terminal.",
+                            }],
+                        details: { isError: false },
+                    };
+                }
+                return {
+                    content: [{
+                            type: "text",
+                            text: JSON.stringify(currentBinding, null, 2),
+                        }],
+                    details: { isError: false },
+                };
+            },
+        });
+        registered++;
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        process.stderr.write(`[aexol-mcp] Failed to register local_get_binding: ${msg}\n`);
+    }
     process.stderr.write(`[aexol-mcp] Registered ${registered} Aexol MCP tool(s) from ${apiUrl}.\n`);
 }

package/dist/server/handlers/paths-autocomplete.js CHANGED Viewed

@@ -7,6 +7,14 @@
  * containing directory, and returns up to 10 directory suggestions whose
  * basenames start with the typed partial segment.
  *
+ * Two strategies:
+ *   1. If the expanded prefix exists on disk as a directory — show its
+ *      immediate children (trailing separator is implicit). This is the
+ *      natural behaviour when the user has already typed a real directory
+ *      and wants to drill deeper.
+ *   2. Otherwise — split into parent + basename prefix and do a
+ *      starts-with match so the user can filter siblings while typing.
+ *
  * Dotfiles are excluded — they are rarely intentional project roots.
  * Symlinks to directories ARE included (readdirSync with withFileTypes
  * returns true for both real dirs and symlink dirs).
@@ -15,27 +23,62 @@
  * fs ops block the event loop for microseconds on local SSDs; the form
  * is typed by a single human, so this is perfectly fine.
  */
-import { readdirSync } from "node:fs";
+import { readdirSync, statSync } from "node:fs";
 import { join, sep } from "node:path";
 import { expandPath } from "../paths.js";
+/** Maximum number of suggestions returned to the UI. */
+const MAX_SUGGESTIONS = 10;
+/**
+ * Build a suggestion list from `parentDir`, filtering directories whose
+ * basename starts with `basenamePrefix` (case-sensitive, POSIX).
+ *
+ * Dotfiles are always excluded. Returns at most `MAX_SUGGESTIONS` entries.
+ */
+function collectSuggestions(parentDir, basenamePrefix) {
+    try {
+        const entries = readdirSync(parentDir, { withFileTypes: true });
+        return entries
+            .filter((e) => e.isDirectory() &&
+            e.name.startsWith(basenamePrefix) &&
+            !e.name.startsWith("."))
+            .map((e) => join(parentDir, e.name))
+            .slice(0, MAX_SUGGESTIONS);
+    }
+    catch {
+        // Directory doesn't exist or is unreadable → empty list.
+        return [];
+    }
+}
 /**
- * List directories inside `expandedPrefix`'s parent that start with the
- * trailing (post-separator) segment of the expanded prefix.
+ * List directory suggestions for the given path prefix.
  *
  * Examples (assume $HOME=/Users/alice, dirs are `projects`, `proj-old`,
  * `Documents`, `.config`):
- *   prefix="~/pro"  → expanded="/Users/alice/pro", parent="/Users/alice/"
- *                      → ["/Users/alice/projects", "/Users/alice/proj-old"]
- *   prefix="~/proj" → expanded="/Users/alice/proj"
- *                      → ["/Users/alice/projects"]
- *   prefix="~"      → expanded="/Users/alice", parent="/Users/alice/"
- *                      → all top-level dirs in $HOME (except dotfiles)
+ *   prefix="~"         → expanded="/Users/alice" (exists as dir)
+ *                        → children of /Users/alice/  ["projects","proj-old","Documents"]
+ *   prefix="~/pro"     → expanded="/Users/alice/pro" (does NOT exist)
+ *                        → starts-with "pro" in /Users/alice/  ["projects","proj-old"]
+ *   prefix="~/projects/" → expanded="/Users/alice/projects/" (exists as dir)
+ *                        → children of /Users/alice/projects/
+ *   prefix="~/projects/sr" → expanded="/Users/alice/projects/sr" (does NOT exist)
+ *                        → starts-with "sr" in /Users/alice/projects/
  */
 export function handlePathAutocomplete(prefix) {
     const expanded = expandPath(prefix);
-    // Split into parent directory and basename prefix.
-    // On POSIX, `expanded` is always absolute after expandPath, so we
-    // always hit the else branch below with a trailing sep.
+    // Strategy 1: expanded path is an existing directory → show children.
+    try {
+        const st = statSync(expanded);
+        if (st.isDirectory()) {
+            const parentDir = expanded.endsWith(sep) ? expanded : expanded + sep;
+            const suggestions = collectSuggestions(parentDir, "");
+            return { suggestions, expandedPrefix: expanded };
+        }
+    }
+    catch {
+        // Not a directory or doesn't exist — fall through to prefix matching.
+    }
+    // Strategy 2: expanded path doesn't exist (or exists but isn't a dir).
+    // Split into parent directory + basename prefix and match by starts-with.
     const lastSep = expanded.lastIndexOf(sep);
     let parentDir;
     let basenamePrefix;
@@ -48,20 +91,6 @@ export function handlePathAutocomplete(prefix) {
         parentDir = expanded.slice(0, lastSep + 1);
         basenamePrefix = expanded.slice(lastSep + 1);
     }
-    let suggestions = [];
-    try {
-        const entries = readdirSync(parentDir, { withFileTypes: true });
-        suggestions = entries
-            .filter((e) => e.isDirectory() &&
-            e.name.startsWith(basenamePrefix) &&
-            !e.name.startsWith("."))
-            .map((e) => join(parentDir, e.name))
-            .slice(0, 10); // keep the list short for the UI
-    }
-    catch {
-        // Directory doesn't exist or is unreadable → return empty list.
-        // The caller (dispatcher) returns a 200 with an empty suggestions[]
-        // so the UI can show a "no matching directories" hint.
-    }
+    const suggestions = collectSuggestions(parentDir, basenamePrefix);
     return { suggestions, expandedPrefix: expanded };
 }

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@aexol/spectral",
-  "version": "0.2.13",
+  "version": "0.2.15",
   "description": "Always-on coding agent for Aexol — branded pi wrapper with relay-based browser access.",
   "type": "module",
   "private": false,