keystone-cli 0.1.0

package/src/runner/shell-executor.ts

@@ -0,0 +1,166 @@
+/**
+ * Shell command executor
+ *
+ * ⚠️ SECURITY WARNING:
+ * This executor runs shell commands using `sh -c`, which means:
+ * - User inputs interpolated into commands can lead to command injection
+ * - Malicious inputs like `foo; rm -rf /` will execute multiple commands
+ *
+ * IMPORTANT: Only run workflows from trusted sources.
+ * Commands are executed with the same privileges as the Keystone process.
+ * Expression evaluation happens before shell execution, so expressions
+ * like ${{ inputs.filename }} are evaluated first, then passed to the shell.
+ *
+ * ✅ RECOMMENDED PRACTICE:
+ * Use the escape() function to safely interpolate user inputs:
+ *
+ * steps:
+ *   - id: safe_echo
+ *     type: shell
+ *     run: echo ${{ escape(inputs.user_message) }}
+ *
+ * The escape() function wraps arguments in single quotes and escapes any
+ * single quotes within, preventing command injection attacks.
+ *
+ * See SECURITY.md for more details.
+ */
+
+import { $ } from 'bun';
+import type { ExpressionContext } from '../expression/evaluator.ts';
+import { ExpressionEvaluator } from '../expression/evaluator.ts';
+import type { ShellStep } from '../parser/schema.ts';
+import type { Logger } from './workflow-runner.ts';
+
+/**
+ * Escape a shell argument for safe use in shell commands
+ * Wraps the argument in single quotes and escapes any single quotes within
+ *
+ * Example usage in workflows:
+ * ```yaml
+ * steps:
+ *   - id: safe_echo
+ *     type: shell
+ *     # Use this pattern to safely interpolate user inputs:
+ *     run: echo ${{ inputs.message }}  # Safe: expression evaluation happens first
+ *     # Avoid patterns like: sh -c "echo $USER_INPUT" where USER_INPUT is raw
+ * ```
+ */
+export function escapeShellArg(arg: string): string {
+  // Replace single quotes with '\'' (end quote, escaped quote, start quote)
+  return `'${arg.replace(/'/g, "'\\''")}'`;
+}
+
+export interface ShellResult {
+  stdout: string;
+  stderr: string;
+  exitCode: number;
+}
+
+/**
+ * Check if a command contains potentially dangerous shell metacharacters
+ * Returns true if the command looks like it might contain unescaped user input
+ */
+function detectShellInjectionRisk(command: string): boolean {
+  // Common shell metacharacters that indicate potential injection
+  const dangerousPatterns = [
+    /;[\s]*\w/, // Command chaining with semicolon
+    /\|[\s]*\w/, // Piping (legitimate uses exist, but worth warning)
+    /&&[\s]*\w/, // AND chaining
+    /\|\|[\s]*\w/, // OR chaining
+    /`[^`]+`/, // Command substitution with backticks
+    /\$\([^)]+\)/, // Command substitution with $()
+    />\s*\/dev\/null/, // Output redirection (common in attacks)
+    /rm\s+-rf/, // Dangerous deletion command
+    />\s*[~\/]/, // File redirection to suspicious paths
+    /curl\s+.*\|\s*sh/, // Download and execute pattern
+    /wget\s+.*\|\s*sh/, // Download and execute pattern
+  ];
+
+  return dangerousPatterns.some((pattern) => pattern.test(command));
+}
+
+/**
+ * Execute a shell command using Bun.$
+ */
+export async function executeShell(
+  step: ShellStep,
+  context: ExpressionContext,
+  logger: Logger = console
+): Promise<ShellResult> {
+  // Evaluate the command string
+  const command = ExpressionEvaluator.evaluate(step.run, context) as string;
+
+  // Check for potential shell injection risks
+  if (detectShellInjectionRisk(command)) {
+    logger.warn(
+      `\n⚠️  WARNING: Command contains shell metacharacters that may indicate injection risk:\n   Command: ${command.substring(0, 100)}${command.length > 100 ? '...' : ''}\n   To safely interpolate user inputs, use the escape() function.\n   Example: run: echo \${{ escape(inputs.user_input) }}\n`
+    );
+  }
+
+  // Evaluate environment variables
+  const env: Record<string, string> = {};
+  if (step.env) {
+    for (const [key, value] of Object.entries(step.env)) {
+      env[key] = ExpressionEvaluator.evaluate(value, context) as string;
+    }
+  }
+
+  // Set working directory if specified
+  const cwd = step.dir ? (ExpressionEvaluator.evaluate(step.dir, context) as string) : undefined;
+
+  try {
+    // Execute command using sh -c to allow shell parsing
+    let proc = $`sh -c ${command}`.quiet();
+
+    // Apply environment variables - merge with Bun.env to preserve system PATH and other variables
+    if (Object.keys(env).length > 0) {
+      proc = proc.env({ ...Bun.env, ...env });
+    }
+
+    // Apply working directory
+    if (cwd) {
+      proc = proc.cwd(cwd);
+    }
+
+    // Execute and capture result
+    const result = await proc;
+
+    const stdout = await result.text();
+    const stderr = result.stderr ? result.stderr.toString() : '';
+    const exitCode = result.exitCode;
+
+    return {
+      stdout,
+      stderr,
+      exitCode,
+    };
+  } catch (error) {
+    // Handle shell execution errors (Bun throws ShellError with exitCode, stdout, stderr)
+    if (error && typeof error === 'object' && 'exitCode' in error) {
+      const shellError = error as {
+        exitCode: number;
+        stdout?: Buffer | string;
+        stderr?: Buffer | string;
+      };
+
+      // Convert stdout/stderr to strings if they're buffers
+      const stdout = shellError.stdout
+        ? Buffer.isBuffer(shellError.stdout)
+          ? shellError.stdout.toString()
+          : String(shellError.stdout)
+        : '';
+      const stderr = shellError.stderr
+        ? Buffer.isBuffer(shellError.stderr)
+          ? shellError.stderr.toString()
+          : String(shellError.stderr)
+        : '';
+
+      return {
+        stdout,
+        stderr,
+        exitCode: shellError.exitCode,
+      };
+    }
+    throw error;
+  }
+}

package/src/runner/step-executor.test.ts

@@ -0,0 +1,465 @@
+import { afterAll, afterEach, beforeAll, beforeEach, describe, expect, it, mock } from 'bun:test';
+import { mkdirSync, rmSync } from 'node:fs';
+import { join } from 'node:path';
+import type { ExpressionContext } from '../expression/evaluator';
+import type {
+  FileStep,
+  HumanStep,
+  RequestStep,
+  ShellStep,
+  SleepStep,
+  WorkflowStep,
+} from '../parser/schema';
+import { executeStep } from './step-executor';
+
+// Mock executeLlmStep
+mock.module('./llm-executor', () => ({
+  // @ts-ignore
+  executeLlmStep: mock((_step, _context, _callback) => {
+    return Promise.resolve({ status: 'success', output: 'llm-output' });
+  }),
+}));
+
+interface StepOutput {
+  stdout: string;
+  stderr: string;
+  exitCode: number;
+}
+
+interface RequestOutput {
+  status: number;
+  data: unknown;
+}
+
+// Mock node:readline/promises
+const mockRl = {
+  question: mock(() => Promise.resolve('')),
+  close: mock(() => {}),
+};
+
+mock.module('node:readline/promises', () => ({
+  createInterface: mock(() => mockRl),
+}));
+
+describe('step-executor', () => {
+  let context: ExpressionContext;
+
+  const tempDir = join(process.cwd(), 'temp-step-test');
+
+  beforeAll(() => {
+    try {
+      mkdirSync(tempDir, { recursive: true });
+    } catch (e) {}
+  });
+
+  afterAll(() => {
+    try {
+      rmSync(tempDir, { recursive: true, force: true });
+    } catch (e) {}
+  });
+
+  beforeEach(() => {
+    context = {
+      inputs: {},
+      steps: {},
+    };
+  });
+
+  describe('shell', () => {
+    it('should execute shell command', async () => {
+      const step: ShellStep = {
+        id: 's1',
+        type: 'shell',
+        run: 'echo "hello"',
+      };
+      const result = await executeStep(step, context);
+      expect(result.status).toBe('success');
+      expect((result.output as StepOutput).stdout.trim()).toBe('hello');
+    });
+
+    it('should handle shell failure', async () => {
+      const step: ShellStep = {
+        id: 's1',
+        type: 'shell',
+        run: 'exit 1',
+      };
+      const result = await executeStep(step, context);
+      expect(result.status).toBe('failed');
+      expect(result.error).toContain('exited with code 1');
+    });
+  });
+
+  describe('file', () => {
+    it('should write and read a file', async () => {
+      const filePath = join(tempDir, 'test.txt');
+      const writeStep: FileStep = {
+        id: 'w1',
+        type: 'file',
+        op: 'write',
+        path: filePath,
+        content: 'hello file',
+      };
+      const writeResult = await executeStep(writeStep, context);
+      expect(writeResult.status).toBe('success');
+
+      const readStep: FileStep = {
+        id: 'r1',
+        type: 'file',
+        op: 'read',
+        path: filePath,
+      };
+      const readResult = await executeStep(readStep, context);
+      expect(readResult.status).toBe('success');
+      expect(readResult.output).toBe('hello file');
+    });
+
+    it('should append to a file', async () => {
+      const filePath = join(tempDir, 'append.txt');
+      await executeStep(
+        {
+          id: 'w1',
+          type: 'file',
+          op: 'write',
+          path: filePath,
+          content: 'line 1\n',
+        } as FileStep,
+        context
+      );
+
+      await executeStep(
+        {
+          id: 'a1',
+          type: 'file',
+          op: 'append',
+          path: filePath,
+          content: 'line 2',
+        } as FileStep,
+        context
+      );
+
+      const content = await Bun.file(filePath).text();
+      expect(content).toBe('line 1\nline 2');
+    });
+
+    it('should fail if file not found on read', async () => {
+      const readStep: FileStep = {
+        id: 'r1',
+        type: 'file',
+        op: 'read',
+        path: join(tempDir, 'non-existent.txt'),
+      };
+      const result = await executeStep(readStep, context);
+      expect(result.status).toBe('failed');
+      expect(result.error).toContain('File not found');
+    });
+
+    it('should fail if content missing on write', async () => {
+      // @ts-ignore
+      const step: FileStep = { id: 'f1', type: 'file', op: 'write', path: 'test.txt' };
+      const result = await executeStep(step, context);
+      expect(result.status).toBe('failed');
+      expect(result.error).toBe('Content is required for write operation');
+    });
+
+    it('should fail if content missing on append', async () => {
+      // @ts-ignore
+      const step: FileStep = { id: 'f1', type: 'file', op: 'append', path: 'test.txt' };
+      const result = await executeStep(step, context);
+      expect(result.status).toBe('failed');
+      expect(result.error).toBe('Content is required for append operation');
+    });
+
+    it('should fail for unknown file operation', async () => {
+      // @ts-ignore
+      const step: FileStep = { id: 'f1', type: 'file', op: 'unknown', path: 'test.txt' };
+      const result = await executeStep(step, context);
+      expect(result.status).toBe('failed');
+      expect(result.error).toContain('Unknown file operation');
+    });
+  });
+
+  describe('sleep', () => {
+    it('should sleep for a duration', async () => {
+      const step: SleepStep = {
+        id: 'sl1',
+        type: 'sleep',
+        duration: 10,
+      };
+      const start = Date.now();
+      const result = await executeStep(step, context);
+      const end = Date.now();
+      expect(result.status).toBe('success');
+      expect(end - start).toBeGreaterThanOrEqual(10);
+    });
+  });
+
+  describe('request', () => {
+    const originalFetch = global.fetch;
+
+    beforeEach(() => {
+      // @ts-ignore
+      global.fetch = mock();
+    });
+
+    afterEach(() => {
+      global.fetch = originalFetch;
+    });
+
+    it('should perform an HTTP request', async () => {
+      // @ts-ignore
+      global.fetch.mockResolvedValue(
+        new Response('{"ok":true}', {
+          status: 200,
+          headers: { 'Content-Type': 'application/json' },
+        })
+      );
+
+      const step: RequestStep = {
+        id: 'req1',
+        type: 'request',
+        url: 'https://api.example.com/test',
+        method: 'GET',
+      };
+
+      const result = await executeStep(step, context);
+      expect(result.status).toBe('success');
+      expect((result.output as RequestOutput).data).toEqual({ ok: true });
+    });
+
+    it('should handle form-urlencoded body', async () => {
+      // @ts-ignore
+      global.fetch.mockResolvedValue(new Response('ok'));
+
+      const step: RequestStep = {
+        id: 'req1',
+        type: 'request',
+        url: 'https://api.example.com/post',
+        method: 'POST',
+        headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+        body: { key: 'value', foo: 'bar' },
+      };
+
+      await executeStep(step, context);
+
+      // @ts-ignore
+      const init = global.fetch.mock.calls[0][1];
+      expect(init.body).toBe('key=value&foo=bar');
+    });
+
+    it('should handle non-object body in form-urlencoded', async () => {
+      // @ts-ignore
+      global.fetch.mockResolvedValue(new Response('ok'));
+
+      const step: RequestStep = {
+        id: 'req1',
+        type: 'request',
+        url: 'https://api.example.com/post',
+        method: 'POST',
+        headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+        body: 'raw-body',
+      };
+
+      await executeStep(step, context);
+
+      // @ts-ignore
+      const init = global.fetch.mock.calls[0][1];
+      expect(init.body).toBe('raw-body');
+    });
+
+    it('should auto-set JSON content type for object bodies', async () => {
+      // @ts-ignore
+      global.fetch.mockResolvedValue(new Response('{}'));
+
+      const step: RequestStep = {
+        id: 'req1',
+        type: 'request',
+        url: 'https://api.example.com/post',
+        method: 'POST',
+        body: { foo: 'bar' },
+      };
+
+      await executeStep(step, context);
+
+      // @ts-ignore
+      const init = global.fetch.mock.calls[0][1];
+      expect(init.headers['Content-Type']).toBe('application/json');
+      expect(init.body).toBe('{"foo":"bar"}');
+    });
+
+    it('should handle non-JSON responses', async () => {
+      // @ts-ignore
+      global.fetch.mockResolvedValue(
+        new Response('plain text', {
+          status: 200,
+          headers: { 'Content-Type': 'text/plain' },
+        })
+      );
+
+      const step: RequestStep = {
+        id: 'req1',
+        type: 'request',
+        url: 'https://api.example.com/text',
+        method: 'GET',
+      };
+
+      const result = await executeStep(step, context);
+      // @ts-ignore
+      expect(result.output.data).toBe('plain text');
+    });
+  });
+
+  describe('human', () => {
+    const originalIsTTY = process.stdin.isTTY;
+
+    beforeEach(() => {
+      process.stdin.isTTY = true;
+    });
+
+    afterEach(() => {
+      process.stdin.isTTY = originalIsTTY;
+    });
+
+    it('should handle human confirmation', async () => {
+      mockRl.question.mockResolvedValue('\n');
+
+      const step: HumanStep = {
+        id: 'h1',
+        type: 'human',
+        message: 'Proceed?',
+        inputType: 'confirm',
+      };
+
+      // @ts-ignore
+      const result = await executeStep(step, context, { log: () => {} });
+      expect(result.status).toBe('success');
+      expect(result.output).toBe(true);
+      expect(mockRl.question).toHaveBeenCalled();
+    });
+
+    it('should handle human text input', async () => {
+      mockRl.question.mockResolvedValue('user response');
+
+      const step: HumanStep = {
+        id: 'h1',
+        type: 'human',
+        message: 'What is your name?',
+        inputType: 'text',
+      };
+
+      // @ts-ignore
+      const result = await executeStep(step, context, { log: () => {} });
+      expect(result.status).toBe('success');
+      expect(result.output).toBe('user response');
+    });
+
+    it('should suspend if not a TTY', async () => {
+      process.stdin.isTTY = false;
+
+      const step: HumanStep = {
+        id: 'h1',
+        type: 'human',
+        message: 'Proceed?',
+        inputType: 'confirm',
+      };
+
+      // @ts-ignore
+      const result = await executeStep(step, context, { log: () => {} });
+      expect(result.status).toBe('suspended');
+      expect(result.error).toBe('Proceed?');
+    });
+  });
+
+  describe('workflow', () => {
+    it('should call executeWorkflowFn', async () => {
+      const step: WorkflowStep = {
+        id: 'w1',
+        type: 'workflow',
+        workflow: 'child.yaml',
+      };
+      // @ts-ignore
+      const executeWorkflowFn = mock(() =>
+        Promise.resolve({ status: 'success', output: 'child-output' })
+      );
+
+      // @ts-ignore
+      const result = await executeStep(step, context, undefined, executeWorkflowFn);
+      expect(result.status).toBe('success');
+      expect(result.output).toBe('child-output');
+      expect(executeWorkflowFn).toHaveBeenCalled();
+    });
+
+    it('should fail if executeWorkflowFn is not provided', async () => {
+      const step: WorkflowStep = {
+        id: 'w1',
+        type: 'workflow',
+        workflow: 'child.yaml',
+      };
+      const result = await executeStep(step, context);
+      expect(result.status).toBe('failed');
+      expect(result.error).toContain('Workflow executor not provided');
+    });
+  });
+
+  describe('llm', () => {
+    it('should call executeLlmStep', async () => {
+      // @ts-ignore
+      const step = {
+        id: 'l1',
+        type: 'llm',
+        prompt: 'hello',
+      };
+      const result = await executeStep(step, context);
+      expect(result.status).toBe('success');
+      expect(result.output).toBe('llm-output');
+    });
+  });
+
+  describe('transform', () => {
+    it('should apply transform to output', async () => {
+      const step: ShellStep = {
+        id: 's1',
+        type: 'shell',
+        run: 'echo "json string"',
+        transform: 'output.stdout.toUpperCase().trim()',
+      };
+      const result = await executeStep(step, context);
+      expect(result.status).toBe('success');
+      expect(result.output).toBe('JSON STRING');
+    });
+
+    it('should apply transform with ${{ }} syntax', async () => {
+      const step: ShellStep = {
+        id: 's1',
+        type: 'shell',
+        run: 'echo "hello"',
+        transform: '${{ output.stdout.trim() + " world" }}',
+      };
+      const result = await executeStep(step, context);
+      expect(result.status).toBe('success');
+      expect(result.output).toBe('hello world');
+    });
+
+    it('should handle transform failure', async () => {
+      const step: ShellStep = {
+        id: 's1',
+        type: 'shell',
+        run: 'echo "hello"',
+        transform: 'nonexistent.property',
+      };
+      const result = await executeStep(step, context);
+      expect(result.status).toBe('failed');
+      expect(result.error).toContain('Transform failed');
+    });
+  });
+
+  it('should throw error for unknown step type', async () => {
+    // @ts-ignore
+    const step = {
+      id: 'u1',
+      type: 'unknown',
+    };
+    const result = await executeStep(step, context);
+    expect(result.status).toBe('failed');
+    expect(result.error).toContain('Unknown step type');
+  });
+});