@evalops/maestro 0.10.17 → 0.10.20

package/dist/safety/execpolicy.js

@@ -30,7 +30,7 @@
  * - .maestro/execpolicy (project - evaluated after global)
  */
 import { appendFileSync, existsSync, mkdirSync, readFileSync, writeFileSync, } from "node:fs";
-import { dirname, join } from "node:path";
+import { basename, dirname, join, win32 } from "node:path";
 import { PATHS } from "../config/constants.js";
 import { createLogger } from "../utils/logger.js";
 const logger = createLogger("safety:execpolicy");
@@ -41,6 +41,7 @@ const logger = createLogger("safety:execpolicy");
 export class Policy {
     constructor() {
         this.rulesByProgram = new Map();
+        this.hostExecutables = new Map();
     }
     static empty() {
         return new Policy();
@@ -51,7 +52,7 @@ export class Policy {
         existing.push(rule);
         this.rulesByProgram.set(program, existing);
     }
-    addPrefixRule(prefix, decision, match, notMatch) {
+    addPrefixRule(prefix, decision, match, notMatch, justification) {
         if (prefix.length === 0) {
             throw new Error("prefix cannot be empty");
         }
@@ -63,7 +64,7 @@ export class Policy {
             first,
             rest: rest.map((t) => ({ type: "single", value: t })),
         };
-        const rule = { pattern, decision };
+        const rule = { pattern, decision, justification };
         // Validate match examples
         if (match) {
             for (const example of match) {
@@ -82,6 +83,16 @@ export class Policy {
         }
         this.addRule(rule);
     }
+    addHostExecutable(name, paths) {
+        if (!name) {
+            throw new Error("host executable name cannot be empty");
+        }
+        const existing = this.hostExecutables.get(name) ?? new Set();
+        for (const path of paths) {
+            existing.add(path);
+        }
+        this.hostExecutables.set(name, existing);
+    }
     ruleMatchesCommand(rule, cmd) {
         const matched = this.matchPrefix(rule.pattern, cmd);
         return matched !== null;
@@ -109,20 +120,53 @@ export class Policy {
         }
         return pattern.values.includes(token);
     }
-    check(cmd, heuristicsFallback) {
-        const matchedRules = this.matchesForCommand(cmd, heuristicsFallback);
+    check(cmd, heuristicsFallback, options = {}) {
+        const matchedRules = this.matchesForCommand(cmd, heuristicsFallback, options);
         return this.evaluationFromMatches(matchedRules);
     }
-    checkMultiple(commands, heuristicsFallback) {
-        const matchedRules = commands.flatMap((cmd) => this.matchesForCommand(cmd, heuristicsFallback));
+    checkMultiple(commands, heuristicsFallback, options = {}) {
+        const matchedRules = commands.flatMap((cmd) => this.matchesForCommand(cmd, heuristicsFallback, options));
         return this.evaluationFromMatches(matchedRules);
     }
-    matchesForCommand(cmd, heuristicsFallback) {
+    matchesForCommand(cmd, heuristicsFallback, options = {}) {
         const program = cmd[0];
         if (!program) {
             return [];
         }
-        const rules = this.rulesByProgram.get(program) ?? [];
+        const exactRules = this.rulesByProgram.get(program) ?? [];
+        const matched = this.collectPrefixMatches(exactRules, cmd);
+        if (matched.length === 0 &&
+            options.resolveHostExecutables &&
+            isPathLikeProgram(program)) {
+            const resolvedProgram = program;
+            for (const fallbackProgram of this.hostExecutableFallbackPrograms(resolvedProgram)) {
+                const fallbackRules = this.rulesByProgram.get(fallbackProgram) ?? [];
+                if (fallbackRules.length > 0 &&
+                    this.canUseHostExecutableFallback(fallbackProgram, resolvedProgram)) {
+                    matched.push(...this.collectPrefixMatches(fallbackRules, [fallbackProgram, ...cmd.slice(1)], resolvedProgram));
+                }
+            }
+        }
+        if (matched.length === 0 && heuristicsFallback) {
+            matched.push({
+                type: "heuristics",
+                command: cmd,
+                decision: heuristicsFallback(cmd),
+            });
+        }
+        return matched;
+    }
+    hostExecutableFallbackPrograms(resolvedProgram) {
+        const programs = new Set();
+        for (const [name, paths] of this.hostExecutables) {
+            if (paths.has(resolvedProgram)) {
+                programs.add(name);
+            }
+        }
+        programs.add(hostExecutableBasename(resolvedProgram));
+        return [...programs];
+    }
+    collectPrefixMatches(rules, cmd, resolvedProgram) {
         const matched = [];
         for (const rule of rules) {
             const matchedPrefix = this.matchPrefix(rule.pattern, cmd);
@@ -131,18 +175,17 @@ export class Policy {
                     type: "prefix",
                     matchedPrefix,
                     decision: rule.decision,
+                    justification: rule.justification,
+                    resolvedProgram,
                 });
             }
         }
-        if (matched.length === 0 && heuristicsFallback) {
-            matched.push({
-                type: "heuristics",
-                command: cmd,
-                decision: heuristicsFallback(cmd),
-            });
-        }
         return matched;
     }
+    canUseHostExecutableFallback(name, resolvedProgram) {
+        const allowedPaths = this.hostExecutables.get(name);
+        return allowedPaths?.has(resolvedProgram) === true;
+    }
     evaluationFromMatches(matchedRules) {
         // Decision priority: forbidden > prompt > allow
         const decisionOrder = ["allow", "prompt", "forbidden"];
@@ -162,6 +205,9 @@ export class Policy {
     get rules() {
         return this.rulesByProgram;
     }
+    get hostExecutablePaths() {
+        return this.hostExecutables;
+    }
 }
 /**
  * Parse a Starlark-like policy file.
@@ -169,8 +215,24 @@ export class Policy {
  */
 export function parsePolicy(content, identifier) {
     const policy = new Policy();
+    const hostExecutableRegex = /host_executable\s*\(\s*([\s\S]*?)\s*\)\s*(?:,?\s*(?=host_executable|prefix_rule|$))/g;
+    for (const match of content.matchAll(hostExecutableRegex)) {
+        const args = match[1];
+        if (!args)
+            continue;
+        try {
+            const parsed = parseHostExecutableArgs(args);
+            policy.addHostExecutable(parsed.name, parsed.paths);
+        }
+        catch (error) {
+            logger.warn(`Failed to parse host executable in ${identifier}`, {
+                error: error instanceof Error ? error.message : String(error),
+                args: args.slice(0, 100),
+            });
+        }
+    }
     // Simple regex-based parser for prefix_rule calls
-    const ruleRegex = /prefix_rule\s*\(\s*([\s\S]*?)\s*\)\s*(?:,?\s*(?=prefix_rule|$))/g;
+    const ruleRegex = /prefix_rule\s*\(\s*([\s\S]*?)\s*\)\s*(?:,?\s*(?=host_executable|prefix_rule|$))/g;
     for (const match of content.matchAll(ruleRegex)) {
         const args = match[1];
         if (!args)
@@ -199,6 +261,7 @@ export function parsePolicy(content, identifier) {
                 const rule = {
                     pattern: { ...pattern, first: firstAlt },
                     decision: parsed.decision,
+                    justification: parsed.justification,
                 };
                 // Validate match examples
                 for (const example of parsed.match) {
@@ -281,6 +344,10 @@ function parsePrefixRuleArgs(args) {
             result.decision = d;
         }
     }
+    const justification = parseNamedStringArg(args, "justification");
+    if (justification) {
+        result.justification = justification;
+    }
     // Parse match=...
     const matchMatch = args.match(/(?<![_])match\s*=\s*(\[[\s\S]*?\](?:\s*,)?)/);
     if (matchMatch?.[1]) {
@@ -296,6 +363,32 @@ function parsePrefixRuleArgs(args) {
     }
     return result;
 }
+function parseHostExecutableArgs(args) {
+    const name = parseNamedStringArg(args, "name");
+    if (!name) {
+        throw new Error("host_executable name is required");
+    }
+    const pathsMatch = args.match(/paths\s*=\s*(\[[\s\S]*?\])/);
+    const paths = pathsMatch?.[1] ? parseStringArray(pathsMatch[1]) : [];
+    return {
+        name,
+        paths,
+    };
+}
+function parseNamedStringArg(args, name) {
+    const doubleQuoted = new RegExp(`${name}\\s*=\\s*"([^"\\\\]*(?:\\\\.[^"\\\\]*)*)"`).exec(args);
+    if (doubleQuoted?.[1] !== undefined) {
+        return unescapePolicyString(doubleQuoted[1]);
+    }
+    const singleQuoted = new RegExp(`${name}\\s*=\\s*'([^'\\\\]*(?:\\\\.[^'\\\\]*)*)'`).exec(args);
+    if (singleQuoted?.[1] !== undefined) {
+        return unescapePolicyString(singleQuoted[1]);
+    }
+    return undefined;
+}
+function unescapePolicyString(value) {
+    return value.replace(/\\(["'\\])/g, "$1");
+}
 function parsePatternArray(str) {
     const result = [];
     const content = str.slice(1, -1).trim();
@@ -420,12 +513,14 @@ function parseExamplesArray(str) {
                 i++;
             }
             i++;
-            // Simple shell-like split
-            const tokens = value.split(/\s+/).filter(Boolean);
+            const tokens = parseCommand(value);
             if (tokens.length > 0) {
                 result.push(tokens);
             }
         }
+        else {
+            i++;
+        }
     }
     return result;
 }
@@ -454,6 +549,9 @@ export function loadPolicy(workspaceDir) {
                     policy.addRule(rule);
                 }
             }
+            for (const [name, paths] of parsed.hostExecutablePaths) {
+                policy.addHostExecutable(name, [...paths]);
+            }
             logger.debug("Loaded global execpolicy", { path: globalPath });
         }
         catch (error) {
@@ -472,6 +570,9 @@ export function loadPolicy(workspaceDir) {
                     policy.addRule(rule);
                 }
             }
+            for (const [name, paths] of parsed.hostExecutablePaths) {
+                policy.addHostExecutable(name, [...paths]);
+            }
             logger.debug("Loaded project execpolicy", { path: projectPath });
         }
         catch (error) {
@@ -528,19 +629,49 @@ export function appendAllowPrefixRule(policyPath, prefix) {
  * Parse a command string into tokens.
  */
 export function parseCommand(command) {
+    return parseCommandSequence(command)[0] ?? [];
+}
+function parseCommandSequence(command) {
+    const commands = [];
     const tokens = [];
     let current = "";
     let inQuotes = false;
     let quoteChar = "";
-    let isEscaped = false;
-    for (const char of command) {
-        if (isEscaped) {
-            current += char;
-            isEscaped = false;
-            continue;
+    const flushToken = () => {
+        if (current) {
+            tokens.push(current);
+            current = "";
+        }
+    };
+    const flushCommand = () => {
+        flushToken();
+        const commandTokens = normalizeShellCommandTokens(tokens);
+        if (commandTokens.length > 0) {
+            commands.push(commandTokens);
         }
+        tokens.length = 0;
+    };
+    for (let i = 0; i < command.length; i++) {
+        const char = command.charAt(i);
         if (char === "\\") {
-            isEscaped = true;
+            const nextChar = command.charAt(i + 1);
+            if (shouldEscapeBackslash(nextChar, inQuotes, quoteChar)) {
+                if (nextChar !== "\n") {
+                    current += nextChar;
+                }
+                i++;
+            }
+            else {
+                current += char;
+            }
+            continue;
+        }
+        if (!inQuotes && isShellCommandSeparator(command, i)) {
+            flushCommand();
+            if ((command.charAt(i) === "&" && command.charAt(i + 1) === "&") ||
+                (command.charAt(i) === "|" && command.charAt(i + 1) === "|")) {
+                i++;
+            }
             continue;
         }
         if (!inQuotes && (char === '"' || char === "'")) {
@@ -554,26 +685,101 @@ export function parseCommand(command) {
             continue;
         }
         if (!inQuotes && /\s/.test(char)) {
-            if (current) {
-                tokens.push(current);
-                current = "";
-            }
+            flushToken();
             continue;
         }
         current += char;
     }
-    if (current) {
-        tokens.push(current);
+    flushCommand();
+    return commands;
+}
+function isShellCommandSeparator(command, index) {
+    const char = command.charAt(index);
+    if (char === ";") {
+        return true;
+    }
+    if (char === "|") {
+        return command.charAt(index - 1) !== ">";
+    }
+    if (char !== "&") {
+        return false;
+    }
+    if (command.charAt(index + 1) === "&") {
+        return true;
     }
-    return tokens;
+    return (command.charAt(index - 1) !== ">" &&
+        command.charAt(index - 1) !== "<" &&
+        command.charAt(index + 1) !== ">");
+}
+function normalizeShellCommandTokens(tokens) {
+    const normalized = [];
+    let commandStarted = false;
+    for (let i = 0; i < tokens.length; i++) {
+        const token = tokens[i];
+        const redirection = shellRedirection(token);
+        if (redirection) {
+            if (redirection.consumesNextToken) {
+                i++;
+            }
+            continue;
+        }
+        if (!commandStarted && isShellAssignment(token)) {
+            continue;
+        }
+        normalized.push(token);
+        commandStarted = true;
+    }
+    return normalized;
+}
+function isShellAssignment(token) {
+    return /^[A-Za-z_][A-Za-z0-9_]*=/.test(token);
+}
+function shellRedirection(token) {
+    if (/^(?:\d*)?(?:<>|>>|>\||>|<|<&|>&|<<-?)$/.test(token)) {
+        return { consumesNextToken: true };
+    }
+    if (/^&>>?$/.test(token)) {
+        return { consumesNextToken: true };
+    }
+    if (/^(?:\d*)?(?:<>|>>|>\||>|<|<&|>&|<<-?).+/.test(token)) {
+        return { consumesNextToken: false };
+    }
+    if (/^&>>?.+/.test(token)) {
+        return { consumesNextToken: false };
+    }
+    return undefined;
+}
+function isPathLikeProgram(program) {
+    return program.includes("/") || program.includes("\\");
+}
+function hostExecutableBasename(program) {
+    return program.includes("\\") ? win32.basename(program) : basename(program);
+}
+function shouldEscapeBackslash(nextChar, inQuotes, quoteChar) {
+    if (!nextChar) {
+        return false;
+    }
+    if (!inQuotes) {
+        return true;
+    }
+    if (quoteChar === "'") {
+        return false;
+    }
+    return (nextChar === quoteChar ||
+        nextChar === "\\" ||
+        nextChar === "\n" ||
+        nextChar === "$" ||
+        nextChar === "`");
 }
 /**
  * Check a command and return the evaluation result.
  */
 export function checkCommand(command, workspaceDir, heuristicsFallback) {
     const policy = loadPolicy(workspaceDir);
-    const tokens = parseCommand(command);
-    return policy.check(tokens, heuristicsFallback);
+    const commands = parseCommandSequence(command);
+    return policy.checkMultiple(commands, heuristicsFallback, {
+        resolveHostExecutables: true,
+    });
 }
 /**
  * Check if a command is allowed without prompting.
@@ -593,9 +799,14 @@ export function isCommandForbidden(command, workspaceDir) {
  * Whitelist a command by adding an allow rule to the project policy.
  */
 export function whitelistCommand(workspaceDir, command) {
-    const tokens = parseCommand(command);
     const policyPath = join(workspaceDir, ".maestro", "execpolicy");
-    appendAllowPrefixRule(policyPath, tokens);
+    const commands = parseCommandSequence(command);
+    if (commands.length === 0) {
+        throw new Error("prefix cannot be empty");
+    }
+    for (const tokens of commands) {
+        appendAllowPrefixRule(policyPath, tokens);
+    }
 }
 /**
  * Get policy summary for display.