@aexol/spectral 0.9.234 → 0.9.240

package/dist/utils/augment-path.js

@@ -0,0 +1,234 @@
+/**
+ * PATH augmentation for processes spectral spawns.
+ *
+ * Why this exists:
+ *   A GUI-launched host (Dock, Spotlight, launchd, a `.app` bundle) inherits a
+ *   minimal `PATH` — usually just `/usr/bin:/bin:/usr/sbin:/sbin`. MCP servers
+ *   declared as `npx -y <pkg>` (and every other `npm`/`node`/`git` child
+ *   process) then die with `Executable not found in $PATH: "npx"`. The Electron
+ *   desktop app solved this by augmenting the PATH of the `spectral serve`
+ *   child it spawned. That app is gone; the same logic now lives here so the
+ *   `spectral desktop` wrapper, `spectral serve` itself, and the MCP stdio
+ *   transports all get a usable PATH regardless of how spectral was launched.
+ *
+ * Sources merged, in priority order (first occurrence wins — shell lookup is
+ * left-to-right):
+ *   1. the current process PATH,
+ *   2. macOS `/etc/paths` + `/etc/paths.d/*` (what `path_helper` uses),
+ *   3. `getconf PATH` (the platform default),
+ *   4. well-known Node/npm/Homebrew/Git install directories,
+ *   5. the newest nvm-managed Node `bin` directory.
+ *
+ * Ported from `electron/path-resolver.ts` when the Electron app was removed, so
+ * behaviour is unchanged for existing users.
+ */
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join, normalize } from "node:path";
+import { spawnSync } from "node:child_process";
+/** Platform path-list separator (`;` on Windows, `:` elsewhere). */
+function pathDelimiter() {
+    return process.platform === "win32" ? ";" : ":";
+}
+/**
+ * Returns the case-correct name of the PATH environment variable on this
+ * platform. Windows allows "Path", Unix is usually "PATH".
+ */
+export function getPathEnvKey(env = process.env) {
+    return Object.keys(env).find((key) => key.toLowerCase() === "path") ?? "PATH";
+}
+/**
+ * Split the content of a path-list source into individual directories.
+ *
+ * Two formats show up in practice and both must be handled: one directory per
+ * line (`/etc/paths`, `/etc/paths.d/*`) and a single delimiter-joined line
+ * (`getconf PATH` prints `/usr/bin:/bin:/usr/sbin:/sbin`). The original
+ * `electron/path-resolver.ts` split on newlines only, so the `getconf` output
+ * landed in the Set as one malformed `/usr/bin:/bin:/usr/sbin:/sbin` entry —
+ * harmless-but-wrong, and enough to make `augmentPath()` non-idempotent.
+ */
+function parsePathsContent(content) {
+    return content
+        .split(/\r?\n/)
+        .map((line) => line.trim())
+        .filter((line) => line.length > 0 && !line.startsWith("#"))
+        .flatMap((line) => line.split(pathDelimiter()))
+        .map((entry) => entry.trim())
+        .filter((entry) => entry.length > 0);
+}
+function readMacEtcPaths() {
+    if (process.platform !== "darwin")
+        return [];
+    const paths = [];
+    const etcPaths = "/etc/paths";
+    if (existsSync(etcPaths)) {
+        try {
+            paths.push(...parsePathsContent(readFileSync(etcPaths, "utf-8")));
+        }
+        catch {
+            // ignore
+        }
+    }
+    const pathsD = "/etc/paths.d";
+    if (existsSync(pathsD)) {
+        try {
+            for (const entry of readdirSync(pathsD, { withFileTypes: true })) {
+                if (!entry.isFile())
+                    continue;
+                paths.push(...parsePathsContent(readFileSync(join(pathsD, entry.name), "utf-8")));
+            }
+        }
+        catch {
+            // ignore
+        }
+    }
+    return paths;
+}
+function readGetconfPath() {
+    if (process.platform === "win32")
+        return [];
+    try {
+        const result = spawnSync("getconf", ["PATH"], { encoding: "utf-8", shell: false });
+        if (result.status === 0 && result.stdout) {
+            return parsePathsContent(result.stdout);
+        }
+    }
+    catch {
+        // ignore
+    }
+    return [];
+}
+function knownExtraPaths() {
+    const commonUnix = [
+        "/usr/local/bin",
+        "/usr/local/sbin",
+        "/usr/bin",
+        "/usr/sbin",
+        "/bin",
+        "/sbin",
+        "/opt/bin",
+        "/opt/local/bin",
+    ];
+    const home = homedir();
+    if (process.platform === "darwin") {
+        return [
+            ...commonUnix,
+            "/opt/homebrew/bin",
+            "/opt/homebrew/sbin",
+            "/usr/local/git/bin",
+            join(home, ".local", "bin"),
+        ];
+    }
+    if (process.platform === "win32") {
+        const programFiles = process.env.PROGRAMFILES ?? "C:\\Program Files";
+        const programFilesX86 = process.env["PROGRAMFILES(X86)"] ?? "C:\\Program Files (x86)";
+        return [
+            join(programFiles, "nodejs"),
+            join(programFilesX86, "nodejs"),
+            join(process.env.LOCALAPPDATA ?? join(home, "AppData", "Local"), "npm"),
+            join(home, "AppData", "Roaming", "npm"),
+            join(programFiles, "Git", "cmd"),
+            join(programFilesX86, "Git", "cmd"),
+            join(programFiles, "Git", "bin"),
+            join(programFilesX86, "Git", "bin"),
+        ];
+    }
+    return [...commonUnix, "/usr/local/git/bin", join(home, ".local", "bin")];
+}
+function findLatestNvmNodeBin() {
+    const nvmDir = process.env.NVM_DIR ?? join(homedir(), ".nvm");
+    const versionsDir = join(nvmDir, "versions", "node");
+    if (!existsSync(versionsDir))
+        return null;
+    try {
+        const versions = readdirSync(versionsDir, { withFileTypes: true })
+            .filter((entry) => entry.isDirectory() && entry.name.startsWith("v"))
+            .map((entry) => entry.name);
+        if (versions.length === 0)
+            return null;
+        versions.sort(compareSemverDesc);
+        return join(versionsDir, versions[0], "bin");
+    }
+    catch {
+        return null;
+    }
+}
+function compareSemverDesc(a, b) {
+    const parse = (value) => value
+        .replace(/^v/, "")
+        .split(".")
+        .map((part) => parseInt(part, 10) || 0);
+    const av = parse(a);
+    const bv = parse(b);
+    const len = Math.max(av.length, bv.length);
+    for (let i = 0; i < len; i++) {
+        const an = av[i] ?? 0;
+        const bn = bv[i] ?? 0;
+        if (an !== bn)
+            return bn - an;
+    }
+    return b.localeCompare(a);
+}
+/**
+ * Cached "static" augmentation. `/etc/paths`, `getconf PATH`, the well-known
+ * install dirs and the nvm lookup do not change during the lifetime of a
+ * process, and `augmentPath()` is called on every MCP server connect — so the
+ * `spawnSync("getconf")` happens at most once per process.
+ */
+let staticExtrasCache = null;
+function staticExtraPaths() {
+    if (staticExtrasCache)
+        return staticExtrasCache;
+    const extras = [];
+    extras.push(...readMacEtcPaths());
+    extras.push(...readGetconfPath());
+    extras.push(...knownExtraPaths());
+    const nvmBin = findLatestNvmNodeBin();
+    if (nvmBin)
+        extras.push(nvmBin);
+    staticExtrasCache = extras;
+    return extras;
+}
+/** Test-only hook: forget the cached /etc/paths + getconf + nvm lookup. */
+export function _resetAugmentPathCacheForTests() {
+    staticExtrasCache = null;
+}
+/**
+ * Build an augmented PATH string.
+ *
+ * @param base PATH to start from. Defaults to the current process PATH, so
+ *   callers holding a custom env (e.g. the MCP stdio transport env) can
+ *   augment that instead.
+ */
+export function augmentPath(base) {
+    const current = base ?? process.env[getPathEnvKey()] ?? "";
+    const segments = new Set();
+    const add = (raw) => {
+        if (!raw)
+            return;
+        const trimmed = normalize(raw).replace(/[\\/]+$/, "");
+        if (trimmed)
+            segments.add(trimmed);
+    };
+    current.split(pathDelimiter()).forEach(add);
+    staticExtraPaths().forEach(add);
+    return [...segments].join(pathDelimiter());
+}
+/**
+ * Return a single-entry env patch — `{ PATH: <augmented> }` under the
+ * case-correct key — ready to spread into a spawn `env`.
+ */
+export function augmentedPathEnvPatch(base, env = process.env) {
+    const key = getPathEnvKey(env);
+    return { [key]: augmentPath(base ?? env[key]) };
+}
+/**
+ * Augment `env`'s PATH in place and return it. Used at daemon start so every
+ * descendant (bash tool, dev-process registry, MCP transports, git) inherits a
+ * PATH that can actually find `node`/`npx`/`git`.
+ */
+export function applyAugmentedPath(env = process.env) {
+    const key = getPathEnvKey(env);
+    env[key] = augmentPath(env[key]);
+    return env;
+}

package/dist/utils/open-browser.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Open a URL in the user's default browser, best-effort.
+ *
+ * Used by `spectral desktop` (the browser *is* the desktop UI now that the
+ * Electron shell is gone) and kept separate from `auth-helper.ts`'s inline
+ * variant so both the login flow and the desktop launcher can share one
+ * implementation.
+ *
+ * Never throws: headless boxes, containers and CI have no browser and no
+ * `xdg-open`. Callers print the URL themselves when `opened` is false, so a
+ * missing browser degrades to "copy this link" instead of a failed command.
+ *
+ * Two hard rules, because this hands a URL to a process launcher:
+ *   - only `http(s)` URLs are accepted — anything else (`file:`, `javascript:`,
+ *     a bare string with shell metacharacters) is refused before a process is
+ *     spawned, and
+ *   - the fallback launches the platform opener by argv, never through a shell,
+ *     so no quoting or re-interpretation of the URL can occur.
+ */
+import { spawn } from "node:child_process";
+export interface OpenBrowserResult {
+    opened: boolean;
+    /** Platform command that was attempted — surfaced in failure messages. */
+    command: string;
+    error?: string;
+}
+export interface OpenBrowserDeps {
+    /** Injectable spawn (tests). */
+    spawn?: typeof spawn;
+    /** Injectable `open` module loader (tests). */
+    loadOpen?: () => Promise<unknown>;
+    /** How long to wait for a launched opener to confirm (defaults to 2 s). */
+    confirmTimeoutMs?: number;
+}
+/** How long an opener child gets to report a clean exit. */
+export declare const OPEN_CONFIRM_TIMEOUT_MS = 2000;
+export declare function isSafeBrowserUrl(url: string): boolean;
+/** Build the shell command for the current platform (mirrors auth-helper). */
+export declare function browserOpenCommand(url: string, platform?: NodeJS.Platform): string;
+/**
+ * The same launch as argv for `spawn(..., { shell: false })`. `start` is a
+ * `cmd.exe` builtin, so Windows goes through `cmd /c start` with the URL as a
+ * separate argument — still no shell string to inject into.
+ */
+export declare function browserOpenArgv(url: string, platform?: NodeJS.Platform): {
+    command: string;
+    args: string[];
+};
+/**
+ * Best-effort browser open. Tries the `open` npm package first (it handles
+ * flatpak/WSL and sandbox edge cases) but only accepts it once its child exits
+ * 0, then the plain platform opener by argv.
+ */
+export declare function openBrowser(url: string, platform?: NodeJS.Platform, deps?: OpenBrowserDeps): Promise<OpenBrowserResult>;
+//# sourceMappingURL=open-browser.d.ts.map

package/dist/utils/open-browser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"open-browser.d.ts","sourceRoot":"","sources":["../../src/utils/open-browser.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,EAAE,KAAK,EAAqB,MAAM,oBAAoB,CAAC;AAE9D,MAAM,WAAW,iBAAiB;IAChC,MAAM,EAAE,OAAO,CAAC;IAChB,0EAA0E;IAC1E,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,eAAe;IAC9B,gCAAgC;IAChC,KAAK,CAAC,EAAE,OAAO,KAAK,CAAC;IACrB,+CAA+C;IAC/C,QAAQ,CAAC,EAAE,MAAM,OAAO,CAAC,OAAO,CAAC,CAAC;IAClC,2EAA2E;IAC3E,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAKD,4DAA4D;AAC5D,eAAO,MAAM,uBAAuB,OAAQ,CAAC;AAE7C,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAErD;AAED,8EAA8E;AAC9E,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,kBAAmB,GAAG,MAAM,CAInF;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAC7B,GAAG,EAAE,MAAM,EACX,QAAQ,kBAAmB,GAC1B;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,EAAE,CAAA;CAAE,CAIrC;AAwCD;;;;GAIG;AACH,wBAAsB,WAAW,CAC/B,GAAG,EAAE,MAAM,EACX,QAAQ,kBAAmB,EAC3B,IAAI,GAAE,eAAoB,GACzB,OAAO,CAAC,iBAAiB,CAAC,CA8E5B"}

package/dist/utils/open-browser.js

@@ -0,0 +1,163 @@
+/**
+ * Open a URL in the user's default browser, best-effort.
+ *
+ * Used by `spectral desktop` (the browser *is* the desktop UI now that the
+ * Electron shell is gone) and kept separate from `auth-helper.ts`'s inline
+ * variant so both the login flow and the desktop launcher can share one
+ * implementation.
+ *
+ * Never throws: headless boxes, containers and CI have no browser and no
+ * `xdg-open`. Callers print the URL themselves when `opened` is false, so a
+ * missing browser degrades to "copy this link" instead of a failed command.
+ *
+ * Two hard rules, because this hands a URL to a process launcher:
+ *   - only `http(s)` URLs are accepted — anything else (`file:`, `javascript:`,
+ *     a bare string with shell metacharacters) is refused before a process is
+ *     spawned, and
+ *   - the fallback launches the platform opener by argv, never through a shell,
+ *     so no quoting or re-interpretation of the URL can occur.
+ */
+import { spawn } from "node:child_process";
+/** Only plain http(s) URLs may reach an opener process. */
+const SAFE_URL = /^https?:\/\/[^\s]+$/i;
+/** How long an opener child gets to report a clean exit. */
+export const OPEN_CONFIRM_TIMEOUT_MS = 2_000;
+export function isSafeBrowserUrl(url) {
+    return SAFE_URL.test(url.trim());
+}
+/** Build the shell command for the current platform (mirrors auth-helper). */
+export function browserOpenCommand(url, platform = process.platform) {
+    if (platform === "darwin")
+        return `open "${url}"`;
+    if (platform === "win32")
+        return `start "" "${url}"`;
+    return `xdg-open "${url}"`;
+}
+/**
+ * The same launch as argv for `spawn(..., { shell: false })`. `start` is a
+ * `cmd.exe` builtin, so Windows goes through `cmd /c start` with the URL as a
+ * separate argument — still no shell string to inject into.
+ */
+export function browserOpenArgv(url, platform = process.platform) {
+    if (platform === "darwin")
+        return { command: "open", args: [url] };
+    if (platform === "win32")
+        return { command: "cmd.exe", args: ["/c", "start", "", url] };
+    return { command: "xdg-open", args: [url] };
+}
+/**
+ * Wait for a launched opener to exit cleanly.
+ *
+ * `open` resolves as soon as its child is spawned — the child is what actually
+ * fails on a headless box — so "it returned a process" is not proof anything
+ * opened. Resolves with the exit code, or null when it failed, exited non-zero,
+ * or never reported within `timeoutMs` (the child is killed on timeout so a
+ * hung opener cannot wedge the caller).
+ */
+function waitForOpenerExit(child, timeoutMs) {
+    const cp = child;
+    if (!cp || typeof cp.once !== "function")
+        return Promise.resolve(null);
+    return new Promise((resolve) => {
+        let settled = false;
+        const finish = (code) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            resolve(code);
+        };
+        const timer = setTimeout(() => {
+            try {
+                cp.kill?.();
+            }
+            catch {
+                // already gone
+            }
+            finish(null);
+        }, timeoutMs);
+        timer.unref?.();
+        cp.once("close", (code) => finish(code));
+        cp.once("error", () => finish(null));
+    });
+}
+/**
+ * Best-effort browser open. Tries the `open` npm package first (it handles
+ * flatpak/WSL and sandbox edge cases) but only accepts it once its child exits
+ * 0, then the plain platform opener by argv.
+ */
+export async function openBrowser(url, platform = process.platform, deps = {}) {
+    const command = browserOpenCommand(url, platform);
+    if (!isSafeBrowserUrl(url)) {
+        return { opened: false, command, error: `refused non-http(s) url: ${url}` };
+    }
+    const confirmTimeoutMs = deps.confirmTimeoutMs ?? OPEN_CONFIRM_TIMEOUT_MS;
+    try {
+        const openModule = deps.loadOpen ? await deps.loadOpen() : await import("open");
+        const openFn = (openModule.default ?? openModule);
+        if (typeof openFn === "function") {
+            const child = await openFn(url);
+            if ((await waitForOpenerExit(child, confirmTimeoutMs)) === 0) {
+                return { opened: true, command };
+            }
+            // Unconfirmed or failed: fall through to the plain opener.
+        }
+    }
+    catch {
+        // fall through to the platform opener
+    }
+    const spawnFn = deps.spawn ?? spawn;
+    const argv = browserOpenArgv(url, platform);
+    return new Promise((resolve) => {
+        let settled = false;
+        // Declared up front: `finish` may run before the timer exists (a spawn that
+        // throws, or one that fails synchronously), and reading a `const` that has
+        // not been initialised yet is a TDZ crash inside a promise.
+        let timer;
+        // Set once WE gave up, so the kill's own `close` event (signal-killed, code
+        // null) cannot masquerade as the opener's verdict.
+        let gaveUp = false;
+        const finish = (result) => {
+            if (settled)
+                return;
+            settled = true;
+            if (timer)
+                clearTimeout(timer);
+            resolve(result);
+        };
+        let child;
+        try {
+            // detached + stdio "ignore": the opener outlives this short-lived CLI
+            // process and cannot keep our stdout or the terminal alive.
+            child = spawnFn(argv.command, argv.args, { detached: true, stdio: "ignore" });
+        }
+        catch (err) {
+            finish({ opened: false, command, error: err.message });
+            return;
+        }
+        timer = setTimeout(() => {
+            gaveUp = true;
+            try {
+                child.kill();
+            }
+            catch {
+                // already gone
+            }
+            finish({
+                opened: false,
+                command,
+                error: `${argv.command} did not exit within ${confirmTimeoutMs}ms`,
+            });
+        }, confirmTimeoutMs);
+        timer.unref?.();
+        child.on("error", (err) => finish({ opened: false, command, error: err.message }));
+        child.on("close", (code) => {
+            if (gaveUp)
+                return; // the timeout above already reported the real reason
+            finish(code === 0
+                ? { opened: true, command }
+                : { opened: false, command, error: `${argv.command} exited with code ${code}` });
+        });
+        child.unref();
+    });
+}