keystone-cli 0.1.0

package/src/expression/evaluator.ts

@@ -0,0 +1,517 @@
+import jsepArrow from '@jsep-plugin/arrow';
+import jsepObject from '@jsep-plugin/object';
+import jsep from 'jsep';
+import { escapeShellArg } from '../runner/shell-executor.ts';
+
+// Register plugins
+jsep.plugins.register(jsepArrow);
+jsep.plugins.register(jsepObject);
+
+/**
+ * Expression evaluator for ${{ }} syntax
+ * Supports:
+ * - inputs.field
+ * - secrets.KEY
+ * - steps.step_id.output
+ * - steps.step_id.outputs.field
+ * - item (for foreach)
+ * - Basic JS expressions (arithmetic, comparisons, logical operators)
+ * - Array access, method calls (map, filter, every, etc.)
+ * - Ternary operator
+ *
+ * ⚠️ SECURITY:
+ * This evaluator uses AST-based parsing (jsep) to safely evaluate expressions
+ * without executing arbitrary code. Only whitelisted operations are allowed.
+ */
+
+export interface ExpressionContext {
+  inputs?: Record<string, unknown>;
+  secrets?: Record<string, string>;
+  steps?: Record<string, { output?: unknown; outputs?: Record<string, unknown>; status?: string }>;
+  item?: unknown;
+  index?: number;
+  env?: Record<string, string>;
+}
+
+type ASTNode = jsep.Expression;
+
+interface ArrowFunctionExpression extends jsep.Expression {
+  type: 'ArrowFunctionExpression';
+  params: jsep.Identifier[];
+  body: jsep.Expression;
+}
+
+interface ObjectProperty extends jsep.Expression {
+  type: 'Property';
+  key: jsep.Expression;
+  value: jsep.Expression;
+  computed: boolean;
+  shorthand: boolean;
+}
+
+interface ObjectExpression extends jsep.Expression {
+  type: 'ObjectExpression';
+  properties: ObjectProperty[];
+}
+
+export class ExpressionEvaluator {
+  /**
+   * Evaluate a string that may contain ${{ }} expressions
+   */
+  static evaluate(template: string, context: ExpressionContext): unknown {
+    // Improved regex that handles nested braces (up to 2 levels of nesting)
+    // Matches ${{ ... }} and allows { ... } inside for object literals and arrow functions
+    const expressionRegex = /\$\{\{(?:[^{}]|\{(?:[^{}]|\{[^{}]*\})*\})*\}\}/g;
+
+    // If the entire string is a single expression, return the evaluated value directly
+    const singleExprMatch = template.match(
+      /^\s*\$\{\{(?:[^{}]|\{(?:[^{}]|\{[^{}]*\})*\})*\}\}\s*$/
+    );
+    if (singleExprMatch) {
+      // Extract the expression content between ${{ and }}
+      const expr = singleExprMatch[0].replace(/^\s*\$\{\{\s*|\s*\}\}\s*$/g, '');
+      return ExpressionEvaluator.evaluateExpression(expr, context);
+    }
+
+    // Otherwise, replace all expressions in the string
+    return template.replace(expressionRegex, (match) => {
+      // Extract the expression content between ${{ and }}
+      const expr = match.replace(/^\$\{\{\s*|\s*\}\}$/g, '');
+      const result = ExpressionEvaluator.evaluateExpression(expr, context);
+      return String(result);
+    });
+  }
+
+  /**
+   * Evaluate a single expression (without the ${{ }} wrapper)
+   * This is public to support transform expressions in shell steps
+   */
+  static evaluateExpression(expr: string, context: ExpressionContext): unknown {
+    try {
+      const ast = jsep(expr);
+      return ExpressionEvaluator.evaluateNode(ast, context);
+    } catch (error) {
+      throw new Error(
+        `Failed to evaluate expression "${expr}": ${error instanceof Error ? error.message : String(error)}`
+      );
+    }
+  }
+
+  /**
+   * Evaluate an AST node recursively
+   */
+  private static evaluateNode(node: ASTNode, context: ExpressionContext): unknown {
+    switch (node.type) {
+      case 'Literal':
+        return (node as jsep.Literal).value;
+
+      case 'Identifier': {
+        const name = (node as jsep.Identifier).name;
+
+        // Safe global functions and values
+        const safeGlobals: Record<string, unknown> = {
+          Boolean: Boolean,
+          Number: Number,
+          String: String,
+          Array: Array,
+          Object: Object,
+          Math: Math,
+          Date: Date,
+          JSON: JSON,
+          parseInt: Number.parseInt,
+          parseFloat: Number.parseFloat,
+          isNaN: Number.isNaN,
+          isFinite: Number.isFinite,
+          undefined: undefined,
+          null: null,
+          NaN: Number.NaN,
+          Infinity: Number.Infinity,
+          true: true,
+          false: false,
+          escape: escapeShellArg, // Shell argument escaping for safe command execution
+        };
+
+        // Check safe globals first
+        if (name in safeGlobals) {
+          return safeGlobals[name];
+        }
+
+        // Check if it's an arrow function parameter (stored directly in context)
+        const contextAsRecord = context as Record<string, unknown>;
+        if (name in contextAsRecord && contextAsRecord[name] !== undefined) {
+          return contextAsRecord[name];
+        }
+
+        // Root context variables
+        const rootContext: Record<string, unknown> = {
+          inputs: context.inputs || {},
+          secrets: context.secrets || {},
+          steps: context.steps || {},
+          item: context.item,
+          index: context.index,
+          env: context.env || {},
+          stdout: contextAsRecord.stdout, // For transform expressions
+        };
+
+        if (name in rootContext && rootContext[name] !== undefined) {
+          return rootContext[name];
+        }
+
+        throw new Error(`Undefined variable: ${name}`);
+      }
+
+      case 'MemberExpression': {
+        const memberNode = node as jsep.MemberExpression;
+        const object = ExpressionEvaluator.evaluateNode(memberNode.object, context);
+
+        if (object === null || object === undefined) {
+          return undefined;
+        }
+
+        let property: string | number;
+        if (memberNode.computed) {
+          // Computed access: obj[expr]
+          property = ExpressionEvaluator.evaluateNode(memberNode.property, context) as
+            | string
+            | number;
+        } else {
+          // Dot access: obj.prop
+          property = (memberNode.property as jsep.Identifier).name;
+        }
+
+        const propertyAsRecord = object as Record<string | number, unknown>;
+
+        // Security check for sensitive properties
+        const forbiddenProperties = ['constructor', '__proto__', 'prototype'];
+        if (typeof property === 'string' && forbiddenProperties.includes(property)) {
+          throw new Error(`Access to property ${property} is forbidden`);
+        }
+
+        return propertyAsRecord[property];
+      }
+
+      case 'BinaryExpression': {
+        const binaryNode = node as jsep.BinaryExpression;
+        const left = ExpressionEvaluator.evaluateNode(binaryNode.left, context);
+
+        // Short-circuit for logical operators that jsep might parse as BinaryExpression
+        if (binaryNode.operator === '&&') {
+          return left && ExpressionEvaluator.evaluateNode(binaryNode.right, context);
+        }
+        if (binaryNode.operator === '||') {
+          return left || ExpressionEvaluator.evaluateNode(binaryNode.right, context);
+        }
+
+        const right = ExpressionEvaluator.evaluateNode(binaryNode.right, context);
+
+        switch (binaryNode.operator) {
+          case '+':
+            return (left as number) + (right as number);
+          case '-':
+            return (left as number) - (right as number);
+          case '*':
+            return (left as number) * (right as number);
+          case '/':
+            return (left as number) / (right as number);
+          case '%':
+            return (left as number) % (right as number);
+          case '==':
+            return left === right;
+          case '===':
+            return left === right;
+          case '!=':
+            return left !== right;
+          case '!==':
+            return left !== right;
+          case '<':
+            return (left as number) < (right as number);
+          case '<=':
+            return (left as number) <= (right as number);
+          case '>':
+            return (left as number) > (right as number);
+          case '>=':
+            return (left as number) >= (right as number);
+          default:
+            throw new Error(`Unsupported binary operator: ${binaryNode.operator}`);
+        }
+      }
+
+      case 'UnaryExpression': {
+        const unaryNode = node as jsep.UnaryExpression;
+        const argument = ExpressionEvaluator.evaluateNode(unaryNode.argument, context);
+
+        switch (unaryNode.operator) {
+          case '-':
+            return -(argument as number);
+          case '+':
+            return +(argument as number);
+          case '!':
+            return !argument;
+          default:
+            throw new Error(`Unsupported unary operator: ${unaryNode.operator}`);
+        }
+      }
+
+      case 'LogicalExpression': {
+        const logicalNode = node as jsep.LogicalExpression;
+        const left = ExpressionEvaluator.evaluateNode(logicalNode.left, context);
+
+        // Short-circuit evaluation
+        if (logicalNode.operator === '&&' && !left) {
+          return left;
+        }
+        if (logicalNode.operator === '||' && left) {
+          return left;
+        }
+
+        return ExpressionEvaluator.evaluateNode(logicalNode.right, context);
+      }
+
+      case 'ConditionalExpression': {
+        const conditionalNode = node as jsep.ConditionalExpression;
+        const test = ExpressionEvaluator.evaluateNode(conditionalNode.test, context);
+        return test
+          ? ExpressionEvaluator.evaluateNode(conditionalNode.consequent, context)
+          : ExpressionEvaluator.evaluateNode(conditionalNode.alternate, context);
+      }
+
+      case 'ArrayExpression': {
+        const arrayNode = node as jsep.ArrayExpression;
+        return arrayNode.elements.map((elem) => ExpressionEvaluator.evaluateNode(elem, context));
+      }
+
+      case 'ObjectExpression': {
+        const objectNode = node as unknown as ObjectExpression;
+        const result: Record<string, unknown> = {};
+        for (const prop of objectNode.properties) {
+          const key =
+            prop.key.type === 'Identifier' && !prop.computed
+              ? (prop.key as jsep.Identifier).name
+              : ExpressionEvaluator.evaluateNode(prop.key, context);
+          result[key as string] = ExpressionEvaluator.evaluateNode(prop.value, context);
+        }
+        return result;
+      }
+
+      case 'CallExpression': {
+        const callNode = node as jsep.CallExpression;
+
+        // Evaluate the callee (could be a member expression like arr.map or an identifier like escape())
+        if (callNode.callee.type === 'MemberExpression') {
+          const memberNode = callNode.callee as jsep.MemberExpression;
+          const object = ExpressionEvaluator.evaluateNode(memberNode.object, context);
+          const methodName = (memberNode.property as jsep.Identifier).name;
+
+          // Evaluate arguments, handling arrow functions specially
+          const args = callNode.arguments.map((arg) => {
+            if (arg.type === 'ArrowFunctionExpression') {
+              return ExpressionEvaluator.createArrowFunction(
+                arg as ArrowFunctionExpression,
+                context
+              );
+            }
+            return ExpressionEvaluator.evaluateNode(arg, context);
+          });
+
+          // Allow only safe array/string methods
+          const safeMethods = [
+            'map',
+            'filter',
+            'reduce',
+            'every',
+            'some',
+            'find',
+            'findIndex',
+            'includes',
+            'indexOf',
+            'slice',
+            'concat',
+            'join',
+            'split',
+            'toLowerCase',
+            'toUpperCase',
+            'trim',
+            'startsWith',
+            'endsWith',
+            'replace',
+            'match',
+            'toString',
+            'length',
+            'max',
+            'min',
+            'abs',
+            'round',
+            'floor',
+            'ceil',
+            'stringify',
+            'parse',
+            'keys',
+            'values',
+            'entries',
+          ];
+
+          if (!safeMethods.includes(methodName)) {
+            throw new Error(`Method ${methodName} is not allowed`);
+          }
+
+          // For methods that take callbacks (map, filter, etc.), we need special handling
+          // Since we can't pass AST nodes directly, we'll handle the most common patterns
+          if (object && typeof (object as Record<string, unknown>)[methodName] === 'function') {
+            return (object as Record<string, unknown>)[methodName](...args);
+          }
+
+          throw new Error(`Cannot call method ${methodName} on ${typeof object}`);
+        }
+
+        // Handle standalone function calls (e.g., escape())
+        if (callNode.callee.type === 'Identifier') {
+          const functionName = (callNode.callee as jsep.Identifier).name;
+
+          // Get the function from safe globals or context
+          const func = ExpressionEvaluator.evaluateNode(callNode.callee, context);
+
+          if (typeof func !== 'function') {
+            throw new Error(`${functionName} is not a function`);
+          }
+
+          // Evaluate arguments
+          const args = callNode.arguments.map((arg) => {
+            if (arg.type === 'ArrowFunctionExpression') {
+              return ExpressionEvaluator.createArrowFunction(
+                arg as ArrowFunctionExpression,
+                context
+              );
+            }
+            return ExpressionEvaluator.evaluateNode(arg, context);
+          });
+
+          return func(...args);
+        }
+
+        throw new Error('Only method calls and safe function calls are supported');
+      }
+
+      case 'ArrowFunctionExpression': {
+        // Arrow functions should be handled in the context of CallExpression
+        // If we reach here, it means they're being used outside of a method call
+        return ExpressionEvaluator.createArrowFunction(node as ArrowFunctionExpression, context);
+      }
+
+      default:
+        throw new Error(`Unsupported expression type: ${node.type}`);
+    }
+  }
+
+  /**
+   * Create a JavaScript function from an arrow function AST node
+   */
+  private static createArrowFunction(
+    arrowNode: ArrowFunctionExpression,
+    context: ExpressionContext
+  ): (...args: unknown[]) => unknown {
+    return (...args: unknown[]) => {
+      // Create a new context with arrow function parameters
+      const arrowContext = { ...context };
+
+      // Bind parameters to arguments
+      arrowNode.params.forEach((param, index) => {
+        const paramName = param.name;
+        // Store parameter values in the context at the root level
+        (arrowContext as Record<string, unknown>)[paramName] = args[index];
+      });
+
+      // Evaluate the body with the new context
+      return ExpressionEvaluator.evaluateNode(arrowNode.body, arrowContext);
+    };
+  }
+
+  /**
+   * Check if a string contains any expressions
+   */
+  static hasExpression(str: string): boolean {
+    // Use same improved regex that handles nested braces (up to 2 levels)
+    return /\$\{\{(?:[^{}]|\{(?:[^{}]|\{[^{}]*\})*\})*\}\}/.test(str);
+  }
+
+  /**
+   * Recursively evaluate all expressions in an object
+   */
+  static evaluateObject(obj: unknown, context: ExpressionContext): unknown {
+    if (typeof obj === 'string') {
+      return ExpressionEvaluator.evaluate(obj, context);
+    }
+
+    if (Array.isArray(obj)) {
+      return obj.map((item) => ExpressionEvaluator.evaluateObject(item, context));
+    }
+
+    if (obj !== null && typeof obj === 'object') {
+      const result: Record<string, unknown> = {};
+      for (const [key, value] of Object.entries(obj)) {
+        result[key] = ExpressionEvaluator.evaluateObject(value, context);
+      }
+      return result;
+    }
+
+    return obj;
+  }
+
+  /**
+   * Extract step IDs that this template depends on
+   */
+  static findStepDependencies(template: string): string[] {
+    const dependencies = new Set<string>();
+    const expressionRegex = /\$\{\{(?:[^{}]|\{(?:[^{}]|\{[^{}]*\})*\})*\}\}/g;
+    const matches = template.matchAll(expressionRegex);
+
+    for (const match of matches) {
+      const expr = match[0].replace(/^\$\{\{\s*|\s*\}\}$/g, '');
+      try {
+        const ast = jsep(expr);
+        ExpressionEvaluator.collectStepIds(ast, dependencies);
+      } catch {
+        // Ignore parse errors, they'll be handled at runtime
+      }
+    }
+
+    return Array.from(dependencies);
+  }
+
+  /**
+   * Recursively find step IDs in an AST node
+   */
+  private static collectStepIds(node: jsep.Expression, dependencies: Set<string>): void {
+    if (!node) return;
+
+    if (node.type === 'MemberExpression') {
+      const memberNode = node as jsep.MemberExpression;
+      if (
+        memberNode.object.type === 'Identifier' &&
+        (memberNode.object as jsep.Identifier).name === 'steps'
+      ) {
+        if (memberNode.property.type === 'Identifier' && !memberNode.computed) {
+          dependencies.add((memberNode.property as jsep.Identifier).name);
+        } else if (memberNode.property.type === 'Literal' && memberNode.computed) {
+          dependencies.add(String((memberNode.property as jsep.Literal).value));
+        }
+        return;
+      }
+    }
+
+    // Generic traversal
+    for (const key of Object.keys(node)) {
+      const child = (node as Record<string, unknown>)[key];
+      if (child && typeof child === 'object') {
+        if (Array.isArray(child)) {
+          for (const item of child) {
+            if (item && typeof (item as jsep.Expression).type === 'string') {
+              ExpressionEvaluator.collectStepIds(item as jsep.Expression, dependencies);
+            }
+          }
+        } else if (typeof (child as jsep.Expression).type === 'string') {
+          ExpressionEvaluator.collectStepIds(child as jsep.Expression, dependencies);
+        }
+      }
+    }
+  }
+}

package/src/parser/agent-parser.test.ts

@@ -0,0 +1,123 @@
+import { afterAll, describe, expect, it, spyOn } from 'bun:test';
+import { mkdirSync, rmSync, writeFileSync } from 'node:fs';
+import * as os from 'node:os';
+import { join } from 'node:path';
+import { parseAgent, resolveAgentPath } from './agent-parser';
+
+describe('agent-parser', () => {
+  const tempDir = join(process.cwd(), 'temp-test-agents');
+
+  // Setup temp directory
+  try {
+    mkdirSync(tempDir, { recursive: true });
+  } catch (e) {}
+
+  afterAll(() => {
+    try {
+      rmSync(tempDir, { recursive: true, force: true });
+    } catch (e) {}
+  });
+
+  describe('parseAgent', () => {
+    it('should parse a valid agent markdown file', () => {
+      const agentContent = `---
+name: test-agent
+description: A test agent
+model: gpt-4
+tools:
+  - name: test-tool
+    description: A test tool
+    execution:
+      type: shell
+      run: echo "hello"
+---
+You are a test agent.
+`;
+      const filePath = join(tempDir, 'test-agent.md');
+      writeFileSync(filePath, agentContent);
+
+      const agent = parseAgent(filePath);
+      expect(agent.name).toBe('test-agent');
+      expect(agent.description).toBe('A test agent');
+      expect(agent.model).toBe('gpt-4');
+      expect(agent.tools).toHaveLength(1);
+      expect(agent.tools[0].name).toBe('test-tool');
+      expect(agent.tools[0].execution.id).toBe('tool-test-tool');
+      expect(agent.systemPrompt).toBe('You are a test agent.');
+    });
+
+    it('should inject tool IDs if missing', () => {
+      const agentContent = `---
+name: test-agent
+tools:
+  - name: tool-without-id
+    execution:
+      type: shell
+      run: ls
+---
+`;
+      const filePath = join(tempDir, 'test-id-injection.md');
+      writeFileSync(filePath, agentContent);
+
+      const agent = parseAgent(filePath);
+      expect(agent.tools[0].execution.id).toBe('tool-tool-without-id');
+    });
+
+    it('should throw error for missing frontmatter', () => {
+      const agentContent = 'Just some content without frontmatter';
+      const filePath = join(tempDir, 'invalid-format.md');
+      writeFileSync(filePath, agentContent);
+
+      expect(() => parseAgent(filePath)).toThrow(/Missing frontmatter/);
+    });
+
+    it('should throw error for invalid schema', () => {
+      const agentContent = `---
+name: 123
+---
+Prompt`;
+      const filePath = join(tempDir, 'invalid-schema.md');
+      writeFileSync(filePath, agentContent);
+      expect(() => parseAgent(filePath)).toThrow(/Invalid agent definition/);
+    });
+  });
+
+  describe('resolveAgentPath', () => {
+    it('should resolve agent path in .keystone/workflows/agents', () => {
+      const agentsDir = join(process.cwd(), '.keystone', 'workflows', 'agents');
+      try {
+        mkdirSync(agentsDir, { recursive: true });
+      } catch (e) {}
+
+      const filePath = join(agentsDir, 'my-agent.md');
+      writeFileSync(filePath, '---name: my-agent---');
+
+      const resolved = resolveAgentPath('my-agent');
+      expect(resolved).toBe(filePath);
+    });
+
+    it('should look in the home directory .keystone/workflows/agents folder', () => {
+      const mockHome = join(tempDir, 'mock-home');
+      const keystoneDir = join(mockHome, '.keystone', 'workflows', 'agents');
+      mkdirSync(keystoneDir, { recursive: true });
+
+      const agentPath = join(keystoneDir, 'home-agent.md');
+      writeFileSync(agentPath, '---name: home-agent---');
+
+      const homedirSpy = spyOn(os, 'homedir').mockReturnValue(mockHome);
+
+      try {
+        const resolved = resolveAgentPath('home-agent');
+        expect(resolved).toBe(agentPath);
+      } finally {
+        homedirSpy.mockRestore();
+      }
+    });
+
+    it('should throw error if agent not found', () => {
+      expect(() => resolveAgentPath('non-existent-agent')).toThrow(
+        /Agent "non-existent-agent" not found/
+      );
+    });
+  });
+});

package/src/parser/agent-parser.ts

@@ -0,0 +1,59 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import yaml from 'js-yaml';
+import { type Agent, AgentSchema } from './schema';
+
+export function parseAgent(filePath: string): Agent {
+  const content = readFileSync(filePath, 'utf8');
+  const match = content.match(/^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n([\s\S]*))?$/);
+
+  if (!match) {
+    throw new Error(`Invalid agent format in ${filePath}. Missing frontmatter.`);
+  }
+
+  const frontmatter = yaml.load(match[1]) as Record<string, unknown>;
+
+  // Inject IDs into tool executions if missing
+  if (frontmatter.tools && Array.isArray(frontmatter.tools)) {
+    frontmatter.tools = frontmatter.tools.map((tool: unknown) => {
+      const t = tool as Record<string, unknown>;
+      if (t.execution && typeof t.execution === 'object') {
+        const exec = t.execution as Record<string, unknown>;
+        if (!exec.id) {
+          exec.id = `tool-${t.name || 'unknown'}`;
+        }
+      }
+      return t;
+    });
+  }
+
+  const systemPrompt = match[2]?.trim() || '';
+
+  const agentData = {
+    ...frontmatter,
+    systemPrompt,
+  };
+
+  const result = AgentSchema.safeParse(agentData);
+  if (!result.success) {
+    throw new Error(`Invalid agent definition in ${filePath}: ${result.error.message}`);
+  }
+
+  return result.data;
+}
+
+export function resolveAgentPath(agentName: string): string {
+  const possiblePaths = [
+    join(process.cwd(), '.keystone', 'workflows', 'agents', `${agentName}.md`),
+    join(homedir(), '.keystone', 'workflows', 'agents', `${agentName}.md`),
+  ];
+
+  for (const path of possiblePaths) {
+    if (existsSync(path)) {
+      return path;
+    }
+  }
+
+  throw new Error(`Agent "${agentName}" not found. Expected one of:\n${possiblePaths.join('\n')}`);
+}