feat: expose envsitter match and scan tools

Adds safe matching/scanning endpoints so workflows can validate secrets without reading .env files.

index.ts

@@ -31,6 +31,51 @@ function stripAtPrefix(input: string): string {
     return input.trim().replace(/^@+/, "");
 }
 
+function parseUserRegExp(input: string): RegExp {
+    const trimmed = input.trim();
+    if (!trimmed.startsWith("/")) return new RegExp(trimmed);
+
+    let lastSlashIndex = -1;
+    for (let i = trimmed.length - 1; i >= 1; i -= 1) {
+        if (trimmed[i] !== "/") continue;
+
+        let backslashCount = 0;
+        for (let j = i - 1; j >= 0 && trimmed[j] === "\\"; j -= 1) {
+            backslashCount += 1;
+        }
+
+        const isEscaped = backslashCount % 2 === 1;
+        if (!isEscaped) {
+            lastSlashIndex = i;
+            break;
+        }
+    }
+
+    if (lastSlashIndex === -1) {
+        throw new Error("Invalid regex literal; expected a closing `/`.");
+    }
+
+    const body = trimmed.slice(1, lastSlashIndex);
+    const flags = trimmed.slice(lastSlashIndex + 1);
+    if (!/^[a-z]*$/.test(flags)) {
+        throw new Error("Invalid regex literal flags; expected only letters (e.g. `/abc/i`).");
+    }
+
+    return new RegExp(body, flags);
+}
+
+function resolveCandidate(params: { candidate?: string; candidateEnvVar?: string }): string {
+    if (typeof params.candidate === "string" && params.candidate.length > 0) return params.candidate;
+
+    if (typeof params.candidateEnvVar === "string" && params.candidateEnvVar.length > 0) {
+        const value = process.env[params.candidateEnvVar];
+        if (typeof value === "string" && value.length > 0) return value;
+        throw new Error(`Env var \`${params.candidateEnvVar}\` was not set.`);
+    }
+
+    throw new Error("Candidate is required for this operation. Provide `candidate` or `candidateEnvVar`.");
+}
+
 function getFilePathFromArgs(args: unknown): string | undefined {
     if (!args || typeof args !== "object") return;
     const record = args as Record<string, unknown>;
@@ -68,6 +113,20 @@ function resolveDotEnvPath(params: {
 export const EnvSitterGuard: Plugin = async ({ client, directory, worktree }) => {
     let lastToastAt = 0;
 
+    const matchOps = [
+        "exists",
+        "is_empty",
+        "is_equal",
+        "partial_match_prefix",
+        "partial_match_suffix",
+        "partial_match_regex",
+        "is_number",
+        "is_boolean",
+        "is_string",
+    ] as const;
+
+    const scanDetections = ["jwt", "url", "base64"] as const;
+
     async function notifyBlocked(action: string): Promise<void> {
         const now = Date.now();
         if (now - lastToastAt < 5000) return;
@@ -81,6 +140,8 @@ export const EnvSitterGuard: Plugin = async ({ client, directory, worktree }) =>
                     `${action} of sensitive env files is blocked. Use EnvSitter instead (never prints values):\n` +
                     "- envsitter_keys { filePath: '.env' }\n" +
                     "- envsitter_fingerprint { filePath: '.env', key: 'SOME_KEY' }\n" +
+                    "- envsitter_match { filePath: '.env', key: 'SOME_KEY', op: 'exists' }\n" +
+                    "- envsitter_scan { filePath: '.env', detect: ['jwt','url'] }\n" +
                     "(CLI: `npx envsitter keys --file .env`) ",
             },
         });
@@ -98,6 +159,7 @@ export const EnvSitterGuard: Plugin = async ({ client, directory, worktree }) =>
                 description: "List keys in a .env file (never returns values).",
                 args: {
                     filePath: tool.schema.string().optional(),
+                    filterRegex: tool.schema.string().optional(),
                 },
                 async execute(args) {
                     const resolved = resolveDotEnvPath({
@@ -107,7 +169,13 @@ export const EnvSitterGuard: Plugin = async ({ client, directory, worktree }) =>
                     });
 
                     const es = EnvSitter.fromDotenvFile(resolved.absolutePath);
-                    const keys = await es.listKeys();
+                    const keys = await es.listKeys(
+                        args.filterRegex
+                            ? {
+                                  filter: parseUserRegExp(args.filterRegex),
+                              }
+                            : undefined,
+                    );
 
                     return JSON.stringify({ file: resolved.displayPath, keys }, null, 2);
                 },
@@ -131,6 +199,175 @@ export const EnvSitterGuard: Plugin = async ({ client, directory, worktree }) =>
                     return JSON.stringify({ file: resolved.displayPath, key: args.key, result }, null, 2);
                 },
             }),
+            envsitter_match: tool({
+                description:
+                    "Match key values without printing them. Supports existence/shape checks and outside-in candidate matching.",
+                args: {
+                    filePath: tool.schema.string().optional(),
+                    op: tool.schema.enum(matchOps).optional(),
+                    key: tool.schema.string().optional(),
+                    keys: tool.schema.array(tool.schema.string()).optional(),
+                    allKeys: tool.schema.boolean().optional(),
+                    candidate: tool.schema.string().optional(),
+                    candidateEnvVar: tool.schema.string().optional(),
+                },
+                async execute(args) {
+                    const resolved = resolveDotEnvPath({
+                        worktree,
+                        directory,
+                        filePath: args.filePath ?? ".env",
+                    });
+
+                    const op = args.op ?? "is_equal";
+                    const es = EnvSitter.fromDotenvFile(resolved.absolutePath);
+
+                    const matcher = (() => {
+                        if (op === "exists") return { op } as const;
+                        if (op === "is_empty") return { op } as const;
+                        if (op === "is_number") return { op } as const;
+                        if (op === "is_boolean") return { op } as const;
+                        if (op === "is_string") return { op } as const;
+
+                        const candidate = resolveCandidate({
+                            candidate: args.candidate,
+                            candidateEnvVar: args.candidateEnvVar,
+                        });
+
+                        if (op === "is_equal") {
+                            return { op, candidate } as const;
+                        }
+
+                        if (op === "partial_match_prefix") {
+                            return { op, prefix: candidate } as const;
+                        }
+
+                        if (op === "partial_match_suffix") {
+                            return { op, suffix: candidate } as const;
+                        }
+
+                        if (op === "partial_match_regex") {
+                            return { op, regex: parseUserRegExp(candidate) } as const;
+                        }
+
+                        throw new Error(`Unsupported op: ${op}`);
+                    })();
+
+                    const key = args.key;
+                    const keys = args.keys;
+                    const allKeys = args.allKeys === true;
+
+                    const selectorCount =
+                        Number(typeof key === "string") + Number(Array.isArray(keys) && keys.length > 0) + Number(allKeys);
+                    if (selectorCount !== 1) {
+                        throw new Error("Provide exactly one of: `key`, `keys`, or `allKeys: true`. ");
+                    }
+
+                    if (typeof key === "string") {
+                        const match = await es.matchKey(key, matcher);
+                        return JSON.stringify({ file: resolved.displayPath, key, op: matcher.op, match }, null, 2);
+                    }
+
+                    if (Array.isArray(keys) && keys.length > 0) {
+                        const matches = await es.matchKeyBulk(keys, matcher);
+                        return JSON.stringify({ file: resolved.displayPath, op: matcher.op, matches }, null, 2);
+                    }
+
+                    const matches = await es.matchKeyAll(matcher);
+                    return JSON.stringify({ file: resolved.displayPath, op: matcher.op, matches }, null, 2);
+                },
+            }),
+            envsitter_match_by_key: tool({
+                description: "Bulk match candidates-by-key without printing values (returns booleans only).",
+                args: {
+                    filePath: tool.schema.string().optional(),
+                    candidatesByKey: tool.schema.record(tool.schema.string(), tool.schema.string()).optional(),
+                    candidatesByKeyJson: tool.schema.string().optional(),
+                    candidatesByKeyEnvVar: tool.schema.string().optional(),
+                },
+                async execute(args) {
+                    const resolved = resolveDotEnvPath({
+                        worktree,
+                        directory,
+                        filePath: args.filePath ?? ".env",
+                    });
+
+                    const fromRecord = args.candidatesByKey;
+                    const fromJson = args.candidatesByKeyJson;
+                    const fromEnvVar = args.candidatesByKeyEnvVar;
+
+                    const selectorCount = Number(!!fromRecord) + Number(!!fromJson) + Number(!!fromEnvVar);
+                    if (selectorCount !== 1) {
+                        throw new Error(
+                            "Provide exactly one of: `candidatesByKey`, `candidatesByKeyJson`, or `candidatesByKeyEnvVar`.",
+                        );
+                    }
+
+                    let candidatesByKey: Record<string, string>;
+
+                    if (fromRecord) {
+                        candidatesByKey = fromRecord;
+                    } else {
+                        const json =
+                            typeof fromJson === "string"
+                                ? fromJson
+                                : (() => {
+                                      const envVarName = fromEnvVar as string;
+                                      const value = process.env[envVarName];
+                                      if (typeof value !== "string") throw new Error(`Env var \`${envVarName}\` was not set.`);
+                                      return value;
+                                  })();
+
+                        let parsed: unknown;
+                        try {
+                            parsed = JSON.parse(json);
+                        } catch {
+                            throw new Error("Invalid candidates JSON; expected an object mapping key -> candidate string.");
+                        }
+
+                        if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+                            throw new Error("Invalid candidates JSON; expected an object mapping key -> candidate string.");
+                        }
+
+                        const record = parsed as Record<string, unknown>;
+                        const normalized: Record<string, string> = {};
+                        for (const [key, value] of Object.entries(record)) {
+                            if (typeof value !== "string") {
+                                throw new Error("Invalid candidates JSON; expected every value to be a string.");
+                            }
+                            normalized[key] = value;
+                        }
+                        candidatesByKey = normalized;
+                    }
+
+                    const es = EnvSitter.fromDotenvFile(resolved.absolutePath);
+                    const matches = await es.matchCandidatesByKey(candidatesByKey);
+
+                    return JSON.stringify({ file: resolved.displayPath, matches }, null, 2);
+                },
+            }),
+            envsitter_scan: tool({
+                description: "Scan value shapes (jwt/url/base64) without printing values.",
+                args: {
+                    filePath: tool.schema.string().optional(),
+                    detect: tool.schema.array(tool.schema.enum(scanDetections)).optional(),
+                    keysFilterRegex: tool.schema.string().optional(),
+                },
+                async execute(args) {
+                    const resolved = resolveDotEnvPath({
+                        worktree,
+                        directory,
+                        filePath: args.filePath ?? ".env",
+                    });
+
+                    const es = EnvSitter.fromDotenvFile(resolved.absolutePath);
+                    const findings = await es.scan({
+                        detect: args.detect,
+                        keysFilter: args.keysFilterRegex ? parseUserRegExp(args.keysFilterRegex) : undefined,
+                    });
+
+                    return JSON.stringify({ file: resolved.displayPath, findings }, null, 2);
+                },
+            }),
         },
         "tool.execute.before": async (input, output) => {
             const filePath = getFilePathFromArgs(output.args);