toolstile 0.1.1 → 0.1.2

package/README.md

@@ -6,8 +6,6 @@ Check the MCP server configs your AI agents use, in one command:
 npx toolstile audit
 ```
 
-The same package is also published as `@toolstile/cli` (`npx @toolstile/cli audit`).
-
 It reads the configs of Claude Code, Claude Desktop, Cursor, Codex, VS Code,
 Windsurf, Gemini CLI and Cline and grades them for:
 
@@ -46,7 +44,9 @@ HIGH   Plaintext secret in github (Cursor)
 - Makes no network requests and collects no telemetry.
 - Never prints, stores or sends secret values. Findings name the file and key,
   for example `mcpServers.github.env.GITHUB_TOKEN`, and the kind of secret.
-- About 1,100 lines of TypeScript with one runtime dependency
+- Never quotes a config file: one that cannot be read or parsed is listed with a
+  reason and position only, for example `invalid TOML at line 3, column 12`.
+- About 1,400 lines of TypeScript with one runtime dependency
   ([smol-toml](https://github.com/squirrelchat/smol-toml), for Codex's TOML
   config) and an optional one ([resvg-js](https://github.com/thx/resvg-js), only
   to render `--card` as PNG). Read it before you run it.
@@ -66,6 +66,14 @@ HIGH   Plaintext secret in github (Cursor)
 `--fail-on high` makes it usable in CI or a pre-commit hook for repositories that
 check in `.mcp.json`, `.cursor/mcp.json` or `.vscode/mcp.json`.
 
+Exit codes:
+
+| Code | Meaning |
+| --- | --- |
+| 0 | The audit ran, and no finding reached the `--fail-on` level (or `--fail-on` was not set) |
+| 1 | A finding is at or above the `--fail-on` level |
+| 2 | Invalid options, or the audit itself failed |
+
 ## Scoring
 
 Each distinct problem has a weight: 10 for a leaked secret, plain-http remote or
@@ -117,7 +125,7 @@ Questions and reports: support@toolstile.com.
 
 ## Releases
 
-Both npm packages are published by [GitHub Actions](.github/workflows/publish.yml)
+The npm package is published by [GitHub Actions](.github/workflows/publish.yml)
 with npm trusted publishing and provenance, so each release links back to the
 commit and workflow that built it. No npm token is stored anywhere.
 

package/dist/checks.d.ts

@@ -4,6 +4,9 @@ interface Package {
     registry: "npm" | "pypi" | "docker";
     name: string;
     version: string | null;
+    /** Index of the package in the unwrapped words. */
+    wordIndex: number;
+    /** Index of the package in `args`, or -1 when it is inside `command`. */
     argIndex: number;
 }
 /** Finds the package a launcher such as npx, uvx or docker runs. */

package/dist/checks.js

@@ -41,20 +41,67 @@ const LAUNCHERS = {
     pnpx: "npm",
     uvx: "pypi",
 };
-/** Splits `command` and `args` into words, handling configs that put the whole command in one string. */
+const base = (p) => win32.basename(posix.basename(p)).replace(/\.(cmd|exe)$/i, "");
+const split = (text) => text.trim().split(/\s+/).filter(Boolean);
+/** WSL options that take a value. */
+const WSL_VALUED = new Set(["-d", "--distribution", "--distribution-id", "-u", "--user", "--cd", "--shell-type"]);
+/** Index of the first word after a `cmd /c` or `wsl` wrapper at `start`, or `start` when there is none. */
+function afterWrapper(list, start) {
+    const name = base(list[start] ?? "").toLowerCase();
+    let j = start + 1;
+    if (name === "cmd") {
+        // cmd [/d] [/s] [/q] … /c|/k command
+        while (j < list.length && /^\/[a-z]$/i.test(list[j]) && !/^\/[ck]$/i.test(list[j]))
+            j++;
+        return /^\/[ck]$/i.test(list[j] ?? "") ? j + 1 : start;
+    }
+    if (name === "wsl") {
+        while (j < list.length) {
+            const a = list[j];
+            if (WSL_VALUED.has(a))
+                j += 2;
+            else if (a === "-e" || a === "--exec" || a === "--")
+                return j + 1;
+            else if (a.startsWith("-"))
+                j++;
+            else
+                break;
+        }
+        return j;
+    }
+    return start;
+}
+/**
+ * Splits `command` and `args` into words, handling configs that put the whole command in one string,
+ * and skips Windows wrappers (`cmd /c npx …`, `wsl npx …`) so the real launcher comes first.
+ */
 function words(s) {
     if (!s.command)
-        return [];
-    const command = s.args.length === 0 && /\s/.test(s.command.trim()) ? s.command.trim().split(/\s+/) : [s.command];
-    return [...command, ...s.args];
+        return { list: [], arg: [] };
+    const oneString = s.args.length === 0 && /\s/.test(s.command.trim());
+    let list = oneString ? split(s.command) : [s.command, ...s.args];
+    let arg = oneString ? list.map(() => -1) : list.map((_, i) => i - 1);
+    for (;;) {
+        const start = afterWrapper(list, 0);
+        if (start === 0 || start >= list.length)
+            break;
+        list = list.slice(start);
+        arg = arg.slice(start);
+        // `cmd /c "npx -y pkg"` passes the inner command as one argument.
+        if (list.length === 1 && /\s/.test(list[0].trim())) {
+            const from = arg[0];
+            list = split(list[0]);
+            arg = list.map(() => from);
+        }
+    }
+    return { list, arg };
 }
-const base = (p) => win32.basename(posix.basename(p)).replace(/\.(cmd|exe)$/i, "");
 /** Finds the package a launcher such as npx, uvx or docker runs. */
 export function packageOf(s) {
-    const w = words(s);
+    const { list: w, arg } = words(s);
     if (w.length === 0)
         return null;
-    const cmd = base(w[0]);
+    const cmd = base(w[0]).toLowerCase();
     const sub = w.slice(1);
     let registry = LAUNCHERS[cmd];
     let skip = 0;
@@ -74,6 +121,7 @@ export function packageOf(s) {
         return null;
     const rest = sub.slice(skip);
     const offset = 1 + skip;
+    const at = (spec, i) => parsePackage(registry, spec, i, arg[i] ?? -1);
     // Flags that take a value; their value is not the package.
     const valued = new Set(["-p", "--package", "--from", "--with", "-e", "--env", "-v", "--volume", "--name", "--network", "--mount", "--env-file", "-w", "--workdir", "--entrypoint", "-u", "--user", "--python"]);
     for (let i = 0; i < rest.length; i++) {
@@ -83,41 +131,42 @@ export function packageOf(s) {
         if (a.startsWith("-")) {
             if (valued.has(a)) {
                 if ((a === "--package" || a === "-p" || a === "--from") && registry !== "docker") {
-                    return parsePackage(registry, rest[i + 1] ?? "", offset + i + 1);
+                    return at(rest[i + 1] ?? "", offset + i + 1);
                 }
                 i++;
             }
             continue;
         }
-        return parsePackage(registry, a, offset + i);
+        return at(a, offset + i);
     }
     return null;
 }
-function parsePackage(registry, spec, argIndex) {
+function parsePackage(registry, spec, wordIndex, argIndex) {
     if (!spec)
         return null;
+    const where = { wordIndex, argIndex };
     if (registry === "docker") {
         const at = spec.indexOf("@sha256:");
         if (at > 0)
-            return { registry, name: spec.slice(0, at), version: spec.slice(at + 1), argIndex };
+            return { registry, name: spec.slice(0, at), version: spec.slice(at + 1), ...where };
         const slash = spec.lastIndexOf("/");
         const colon = spec.lastIndexOf(":");
         return colon > slash
-            ? { registry, name: spec.slice(0, colon), version: spec.slice(colon + 1), argIndex }
-            : { registry, name: spec, version: null, argIndex };
+            ? { registry, name: spec.slice(0, colon), version: spec.slice(colon + 1), ...where }
+            : { registry, name: spec, version: null, ...where };
     }
     if (registry === "pypi") {
         const m = /^([A-Za-z0-9._\-[\],]+?)(?:(==|@|>=|~=)(.+))?$/.exec(spec);
         if (!m)
             return null;
-        return { registry, name: m[1], version: m[2] === "==" || m[2] === "@" ? m[3] : null, argIndex };
+        return { registry, name: m[1], version: m[2] === "==" || m[2] === "@" ? m[3] : null, ...where };
     }
     if (/^(https?:|git\+|file:|\.|\/)/.test(spec))
         return null;
     const at = spec.indexOf("@", spec.startsWith("@") ? 1 : 0);
     return at > 0
-        ? { registry, name: spec.slice(0, at), version: spec.slice(at + 1), argIndex }
-        : { registry, name: spec, version: null, argIndex };
+        ? { registry, name: spec.slice(0, at), version: spec.slice(at + 1), ...where }
+        : { registry, name: spec, version: null, ...where };
 }
 const isPinned = (p) => p.version !== null &&
     p.version !== "latest" &&
@@ -138,7 +187,7 @@ export function identityOf(s) {
     const pkg = packageOf(s);
     if (pkg)
         return `${pkg.registry}:${pkg.name.toLowerCase()}`;
-    const w = words(s);
+    const w = words(s).list;
     return w.length ? `cmd:${w.join(" ")}` : null;
 }
 const LOOPBACK = /^(localhost|127\.\d+\.\d+\.\d+|\[::1\]|0\.0\.0\.0)$/i;
@@ -149,7 +198,7 @@ function broadRoots(s, home) {
         return [];
     const homes = new Set([home, home.replace(/\/+$/, ""), "~", "~/", "$HOME", "${HOME}", "%USERPROFILE%"]);
     return words(s)
-        .slice(pkg.argIndex + 1)
+        .list.slice(pkg.wordIndex + 1)
         .filter((a) => a === "/" || /^[A-Za-z]:\\?$/.test(a) || homes.has(a) || homes.has(a.replace(/\/+$/, "")));
 }
 const SEVERITY_ORDER = { high: 0, medium: 1, low: 2, info: 3 };
@@ -250,11 +299,11 @@ export function runChecks(d, home) {
                 fix: pkg.registry === "docker"
                     ? `Pin an image digest or exact tag, for example ${pkg.name}:<version>.`
                     : `Pin an exact version, for example ${pkg.name}${pkg.registry === "pypi" ? "==" : "@"}<version>.`,
-                locations: [at(s, "args", String(Math.max(0, pkg.argIndex - 1)))],
+                locations: [pkg.argIndex >= 0 ? at(s, "args", String(pkg.argIndex)) : at(s, "command")],
                 weight: 4,
             });
         }
-        const w = words(s);
+        const w = words(s).list;
         if (pkg?.registry === "docker") {
             const risky = w.filter((a) => a === "--privileged" || /\/var\/run\/docker\.sock/.test(a) || a === "--net=host" || a === "--network=host");
             if (risky.length) {

package/dist/parse.d.ts

@@ -1,3 +1,17 @@
-/** Parses JSON that may contain comments and trailing commas (VS Code style). */
+/**
+ * A config file that could not be parsed. The message is fixed text plus a position: parser
+ * messages quote the offending source line, which can hold a secret, so they are never kept.
+ */
+export declare class ConfigParseError extends Error {
+    readonly format: "JSON" | "TOML";
+    readonly line?: number | undefined;
+    readonly column?: number | undefined;
+    constructor(format: "JSON" | "TOML", line?: number | undefined, column?: number | undefined);
+}
+/**
+ * Parses JSON that may contain comments and trailing commas (VS Code style). Comments and
+ * trailing commas become spaces so parser positions still match the original text.
+ */
 export declare function parseJsonc(text: string): unknown;
+/** Parses a config file. Throws only {@link ConfigParseError}, whose message never contains file text. */
 export declare function parseConfig(path: string, text: string): unknown;

package/dist/parse.js

@@ -1,5 +1,24 @@
-import { parse as parseToml } from "smol-toml";
-/** Parses JSON that may contain comments and trailing commas (VS Code style). */
+import { parse as parseToml, TomlError } from "smol-toml";
+/**
+ * A config file that could not be parsed. The message is fixed text plus a position: parser
+ * messages quote the offending source line, which can hold a secret, so they are never kept.
+ */
+export class ConfigParseError extends Error {
+    format;
+    line;
+    column;
+    constructor(format, line, column) {
+        super(`invalid ${format}${line ? ` at line ${line}${column ? `, column ${column}` : ""}` : ""}`);
+        this.format = format;
+        this.line = line;
+        this.column = column;
+        this.name = "ConfigParseError";
+    }
+}
+/**
+ * Parses JSON that may contain comments and trailing commas (VS Code style). Comments and
+ * trailing commas become spaces so parser positions still match the original text.
+ */
 export function parseJsonc(text) {
     let out = "";
     let inString = false;
@@ -22,15 +41,19 @@ export function parseJsonc(text) {
             out += ch;
         }
         else if (ch === "/" && next === "/") {
-            while (i < text.length && text[i] !== "\n")
+            while (i < text.length && text[i] !== "\n") {
+                out += blank(text[i]);
                 i++;
-            out += "\n";
+            }
+            if (i < text.length)
+                out += "\n";
         }
         else if (ch === "/" && next === "*") {
-            i += 2;
-            while (i < text.length && !(text[i] === "*" && text[i + 1] === "/"))
-                i++;
-            i++;
+            const end = text.indexOf("*/", i + 2);
+            const stop = end === -1 ? text.length : end + 2;
+            for (; i < stop; i++)
+                out += blank(text[i]);
+            i--;
         }
         else {
             out += ch;
@@ -38,6 +61,8 @@ export function parseJsonc(text) {
     }
     return JSON.parse(stripTrailingCommas(out));
 }
+/** Keeps line breaks so line numbers survive; everything else becomes a space. */
+const blank = (ch) => (ch === "\n" || ch === "\r" ? ch : " ");
 function stripTrailingCommas(text) {
     let out = "";
     let inString = false;
@@ -60,17 +85,51 @@ function stripTrailingCommas(text) {
             let j = i + 1;
             while (j < text.length && /\s/.test(text[j]))
                 j++;
-            if (text[j] === "}" || text[j] === "]")
+            if (text[j] === "}" || text[j] === "]") {
+                out += " ";
                 continue;
+            }
         }
         out += ch;
     }
     return out;
 }
+/** 1-based line and column of a character offset. */
+function lineColumn(text, offset) {
+    const before = text.slice(0, Math.min(Math.max(offset, 0), text.length));
+    const lastBreak = before.lastIndexOf("\n");
+    return { line: before.split("\n").length, column: offset - lastBreak };
+}
+/** Reads only the position from a V8 JSON error; the rest of its message may quote the file. */
+function jsonPosition(error, text) {
+    const message = error instanceof Error ? error.message : "";
+    const at = /\bposition (\d+)/.exec(message);
+    if (at)
+        return lineColumn(text, Number(at[1]));
+    if (/Unexpected end of JSON input/.test(message))
+        return lineColumn(text, text.length);
+    return {};
+}
+/** Parses a config file. Throws only {@link ConfigParseError}, whose message never contains file text. */
 export function parseConfig(path, text) {
-    if (path.endsWith(".toml"))
-        return parseToml(text);
-    if (text.trim() === "")
+    const body = text.charCodeAt(0) === 0xfeff ? text.slice(1) : text;
+    if (path.endsWith(".toml")) {
+        try {
+            return parseToml(body);
+        }
+        catch (error) {
+            if (error instanceof TomlError)
+                throw new ConfigParseError("TOML", error.line, error.column);
+            throw new ConfigParseError("TOML");
+        }
+    }
+    if (body.trim() === "")
         return {};
-    return parseJsonc(text);
+    try {
+        return parseJsonc(body);
+    }
+    catch (error) {
+        const { line, column } = jsonPosition(error, body);
+        throw new ConfigParseError("JSON", line, column);
+    }
 }

package/dist/report.js

@@ -60,7 +60,7 @@ export function renderReport(r, home, s, redacted = false) {
     const clientList = r.clients.map((c) => CLIENT_NAMES[c]).join(", ");
     lines.push(`Scanned ${plural(r.files.length, "file")} from ${clientList}: ${plural(r.servers, "MCP server")}.`);
     for (const u of r.unreadable) {
-        lines.push(s.dim(`Skipped ${tildify(u.path, home)} (${CLIENT_NAMES[u.client]}): could not parse it.`));
+        lines.push(s.dim(`Skipped ${tildify(u.path, home)} (${CLIENT_NAMES[u.client]}): ${u.error}.`));
     }
     lines.push("");
     if (r.grade !== null) {

package/dist/secrets.js

@@ -28,9 +28,9 @@ const PATTERNS = [
     [/\beyJ[A-Za-z0-9_-]{10,}\.eyJ[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}/, "JWT"],
     [/\b[a-z][a-z0-9+.-]*:\/\/[^\s:/@]+:[^\s@/]{3,}@/i, "password in connection string"],
 ];
-const SECRET_KEY = /(token|secret|passw(or)?d|passwd|api[_-]?key|apikey|access[_-]?key|private[_-]?key|client[_-]?secret|credential|auth|bearer|session|cookie|\bpat\b|_pat$|^pat_)/i;
-/** Key suffixes that name configuration about a secret rather than the secret itself. */
-const NOT_SECRET_KEY = /(url|uri|endpoint|host|port|path|file|dir|type|mode|enabled|header|name|user(name)?|id|region|scope|scopes|method|env_var|_var)$/i;
+const SECRET_KEY = /(token|secret|passw(or)?d|passwd|api[_-]?key|apikey|access[_-]?key|private[_-]?key|client[_-]?secret|credential|auth|bearer|session|cookie|\bpat\b|_pat$|^pat_|(^|[_-])key$)/i;
+/** Key suffixes that name configuration about a secret, or a public half, rather than the secret itself. */
+const NOT_SECRET_KEY = /(url|uri|endpoint|host|port|path|file|dir|type|mode|enabled|header|name|user(name)?|id|region|scope|scopes|method|env_var|_var|public[_-]?key)$/i;
 const PLACEHOLDER = /^(<.*>|\{.*\}|\[.*\]|x{4,}|\*{3,}|\.{3,}|your[-_ ].*|change[-_ ]?me|todo|placeholder|example|redacted|none|null|undefined|true|false|test|secret|token)$/i;
 /** True for `${VAR}`, `${env:VAR}`, `$VAR`, `%VAR%` and `{env:VAR}` references. */
 export function isReference(value) {

package/dist/sources.js

@@ -1,6 +1,6 @@
 import { readFileSync, statSync } from "node:fs";
 import { dirname, join, resolve } from "node:path";
-import { parseConfig } from "./parse.js";
+import { ConfigParseError, parseConfig } from "./parse.js";
 export const CLIENT_NAMES = {
     "claude-code": "Claude Code",
     "claude-desktop": "Claude Desktop",
@@ -149,6 +149,14 @@ function ancestorModes(path) {
         dir = parent;
     }
 }
+/** A fixed description of a read failure; system messages are not passed through. */
+function readError(code) {
+    if (code === "EACCES" || code === "EPERM")
+        return "permission denied";
+    if (code === "EISDIR")
+        return "is a directory";
+    return code && /^E[A-Z]+$/.test(code) ? `could not read it (${code})` : "could not read it";
+}
 export function discover(opts) {
     const result = { files: [], unreadable: [], servers: [], approvals: [] };
     for (const c of candidates(opts)) {
@@ -161,7 +169,12 @@ export function discover(opts) {
             mode = opts.platform === "win32" ? undefined : stat.mode & 0o777;
             text = readFileSync(c.path, "utf8");
         }
-        catch {
+        catch (error) {
+            const code = error.code;
+            // Absent files are normal; anything else means a config exists that we could not check.
+            if (code !== "ENOENT" && code !== "ENOTDIR") {
+                result.unreadable.push({ client: c.client, path: c.path, error: readError(code) });
+            }
             continue;
         }
         let data;
@@ -169,7 +182,9 @@ export function discover(opts) {
             data = parseConfig(c.path, text);
         }
         catch (error) {
-            result.unreadable.push({ client: c.client, path: c.path, error: error.message });
+            // parseConfig's messages are fixed text plus a position, never file contents.
+            const message = error instanceof ConfigParseError ? error.message : "could not parse it";
+            result.unreadable.push({ client: c.client, path: c.path, error: message });
             continue;
         }
         const exposure = mode === undefined ? undefined : exposureOf(mode, ancestorModes(c.path));

package/dist/types.d.ts

@@ -55,7 +55,10 @@ export interface AuditResult {
         client: ClientId;
         path: string;
     }[];
-    /** Files that exist but could not be parsed. */
+    /**
+     * Files that exist but could not be read or parsed. `error` is a fixed description with at most
+     * a line and column, for example `invalid TOML at line 3, column 12`; it never quotes the file.
+     */
     unreadable: {
         client: ClientId;
         path: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "toolstile",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "Audit the MCP server configs your AI agents use for plaintext secrets, unpinned packages, auto-approved tools and duplicated setups. Local and read-only.",
   "keywords": [
     "mcp",
@@ -37,8 +37,8 @@
   "scripts": {
     "build": "rm -rf dist && tsc -p tsconfig.build.json && chmod +x dist/cli.js",
     "typecheck": "tsc --noEmit",
-    "test": "vitest run",
-    "prepublishOnly": "pnpm typecheck && pnpm build && pnpm test"
+    "test": "pnpm build && vitest run",
+    "prepublishOnly": "pnpm typecheck && pnpm test"
   },
   "dependencies": {
     "smol-toml": "^1.9.1"