takos-actions-engine 1.0.0

package/src/__tests__/scheduler/listener-registry.test.ts

@@ -0,0 +1,95 @@
+import { describe, expect, it } from 'vitest';
+
+import { JobScheduler, type JobSchedulerEvent } from '../../scheduler/job.js';
+import { createBaseContext } from '../../context.js';
+import type { Workflow } from '../../workflow-models.js';
+
+/**
+ * Minimal workflow used purely to construct a JobScheduler instance.
+ */
+function createMinimalWorkflow(): Workflow {
+  return {
+    name: 'listener-test',
+    on: 'push',
+    jobs: {
+      a: { 'runs-on': 'ubuntu-latest', steps: [{ run: 'echo ok' }] },
+    },
+  };
+}
+
+describe('JobScheduler listener management', () => {
+  it('keeps current emit stable when a listener is removed during emit', async () => {
+    const scheduler = new JobScheduler(createMinimalWorkflow());
+    const callOrder: string[] = [];
+
+    let unsubscribeSecond = () => {};
+
+    scheduler.on(() => {
+      callOrder.push('first');
+      unsubscribeSecond();
+    });
+    unsubscribeSecond = scheduler.on(() => {
+      callOrder.push('second');
+    });
+
+    // Run triggers multiple emit calls; capture events from the first emit
+    await scheduler.run(createBaseContext());
+
+    // The first event emitted is 'workflow:start'. Both listeners should have
+    // been called for that first emit because removal happens on a snapshot.
+    expect(callOrder[0]).toBe('first');
+    expect(callOrder[1]).toBe('second');
+    // After the first emit, the second listener should be gone.
+    // Subsequent emits should only include 'first'.
+    const afterFirstEmit = callOrder.slice(2);
+    expect(afterFirstEmit.every((v) => v === 'first')).toBe(true);
+  });
+
+  it('defers listeners added during emit until the next emit cycle', async () => {
+    const scheduler = new JobScheduler(createMinimalWorkflow());
+    const callOrder: string[] = [];
+
+    const lateListener = () => {
+      callOrder.push('late');
+    };
+
+    let addedLate = false;
+    scheduler.on(() => {
+      callOrder.push('first');
+      if (!addedLate) {
+        scheduler.on(lateListener);
+        addedLate = true;
+      }
+    });
+
+    await scheduler.run(createBaseContext());
+
+    // 'late' should NOT appear for the first emit, only for subsequent emits.
+    expect(callOrder[0]).toBe('first');
+    expect(callOrder[1]).not.toBe('late');
+  });
+
+  it('continues calling remaining listeners even if an earlier listener throws', async () => {
+    const scheduler = new JobScheduler(createMinimalWorkflow());
+    const callOrder: string[] = [];
+
+    scheduler.on(() => {
+      callOrder.push('first');
+      throw new Error('listener failed');
+    });
+    scheduler.on(() => {
+      callOrder.push('second');
+    });
+    scheduler.on(() => {
+      callOrder.push('third');
+    });
+
+    // Should not throw despite a listener throwing
+    await expect(scheduler.run(createBaseContext())).resolves.toBeDefined();
+
+    // All three listeners should have been called for at least the first emit
+    expect(callOrder.includes('first')).toBe(true);
+    expect(callOrder.includes('second')).toBe(true);
+    expect(callOrder.includes('third')).toBe(true);
+  });
+});

package/src/__tests__/scheduler/step.test.ts

@@ -0,0 +1,258 @@
+import { appendFileSync, mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import { describe, expect, it } from 'vitest';
+
+import { createBaseContext } from '../../context.js';
+import type { Step } from '../../workflow-models.js';
+import { StepRunner } from '../../scheduler/step.js';
+
+async function withProcessPlatform<T>(
+  platform: NodeJS.Platform,
+  run: () => Promise<T>
+): Promise<T> {
+  const platformDescriptor = Object.getOwnPropertyDescriptor(process, 'platform');
+  if (!platformDescriptor) {
+    throw new Error('Unable to read process.platform descriptor');
+  }
+
+  Object.defineProperty(process, 'platform', { value: platform });
+  try {
+    return await run();
+  } finally {
+    Object.defineProperty(process, 'platform', platformDescriptor);
+  }
+}
+
+describe('step output parsing', () => {
+  it('parses legacy and simple outputs while ignoring malformed lines', async () => {
+    const stdout = [
+      '::set-output name=legacy::from-legacy',
+      '::set-output name=legacy_empty::',
+      'simple_output=from-simple',
+      'legacy=from-simple-duplicate',
+      'not-valid=value',
+      'empty=',
+    ].join('\n');
+
+    const runner = new StepRunner({
+      shellExecutor: async () => ({
+        exitCode: 0,
+        stdout,
+        stderr: '',
+      }),
+    });
+
+    const step: Step = { id: 'parse-outputs', run: 'echo output' };
+    const result = await runner.runStep(step, createBaseContext());
+
+    expect(result.outputs).toEqual({
+      legacy: 'from-legacy',
+      legacy_empty: '',
+      simple_output: 'from-simple',
+      empty: '',
+    });
+  });
+
+  it('handles long legacy output lines', async () => {
+    const longName = 'A'.repeat(20_000);
+    const stdout = `::set-output name=${longName}::value`;
+
+    const runner = new StepRunner({
+      shellExecutor: async () => ({
+        exitCode: 0,
+        stdout,
+        stderr: '',
+      }),
+    });
+
+    const step: Step = { id: 'long-outputs', run: 'echo output' };
+    const result = await runner.runStep(step, createBaseContext());
+
+    expect(result.outputs[longName]).toBe('value');
+  });
+
+  it('reads command-file outputs and supports empty initial GitHub vars', async () => {
+    const capturedEnv: Array<Record<string, string> | undefined> = [];
+    const runner = new StepRunner({
+      shellExecutor: async (_command, options) => {
+        capturedEnv.push(options.env);
+        const outputFile = options.env?.GITHUB_OUTPUT;
+        expect(outputFile).toBeTruthy();
+        appendFileSync(outputFile!, 'from_file=hello\n');
+        appendFileSync(outputFile!, 'multi<<EOF\nline1\nline2\nEOF\n');
+        return {
+          exitCode: 0,
+          stdout: 'from_stdout=ok',
+          stderr: '',
+        };
+      },
+    });
+
+    const context = createBaseContext({ env: {} });
+    const step: Step = { id: 'command-file-outputs', run: 'echo output' };
+    const result = await runner.runStep(step, context);
+
+    expect(result.outputs).toEqual({
+      from_stdout: 'ok',
+      from_file: 'hello',
+      multi: 'line1\nline2',
+    });
+
+    const firstEnv = capturedEnv[0];
+    expect(firstEnv?.GITHUB_ENV).toBeTruthy();
+    expect(firstEnv?.GITHUB_OUTPUT).toBeTruthy();
+    expect(firstEnv?.GITHUB_PATH).toBeTruthy();
+  });
+
+  it('parses command-file heredoc outputs written with CRLF line endings', async () => {
+    const runner = new StepRunner({
+      shellExecutor: async (_command, options) => {
+        const outputFile = options.env?.GITHUB_OUTPUT;
+        expect(outputFile).toBeTruthy();
+        appendFileSync(outputFile!, 'multi<<EOF\r\nline1\r\nline2\r\nEOF\r\n');
+        return {
+          exitCode: 0,
+          stdout: '',
+          stderr: '',
+        };
+      },
+    });
+
+    const context = createBaseContext({ env: {} });
+    const step: Step = { id: 'command-file-outputs-crlf', run: 'echo output' };
+    const result = await runner.runStep(step, context);
+
+    expect(result.outputs).toEqual({
+      multi: 'line1\nline2',
+    });
+    expect(result.outputs.multi.includes('\r')).toBe(false);
+  });
+});
+
+describe('step default executors', () => {
+  it('uses pwsh by default on win32', async () => {
+    let observedShell: Step['shell'] | undefined;
+
+    await withProcessPlatform('win32', async () => {
+      const runner = new StepRunner({
+        shellExecutor: async (_command, options) => {
+          observedShell = options.shell;
+          return { exitCode: 0, stdout: '', stderr: '' };
+        },
+      });
+
+      await runner.runStep({ id: 'win32-default-shell', run: 'echo ok' }, createBaseContext());
+    });
+
+    expect(observedShell).toBe('pwsh');
+  });
+
+  it('uses bash by default on non-win32 platforms', async () => {
+    let observedShell: Step['shell'] | undefined;
+
+    await withProcessPlatform('linux', async () => {
+      const runner = new StepRunner({
+        shellExecutor: async (_command, options) => {
+          observedShell = options.shell;
+          return { exitCode: 0, stdout: '', stderr: '' };
+        },
+      });
+
+      await runner.runStep({ id: 'non-win32-default-shell', run: 'echo ok' }, createBaseContext());
+    });
+
+    expect(observedShell).toBe('bash');
+  });
+
+  it('prioritizes explicit shell configuration over platform defaults', async () => {
+    const observedShells: Array<Step['shell'] | undefined> = [];
+
+    await withProcessPlatform('win32', async () => {
+      const runner = new StepRunner({
+        defaultShell: 'bash',
+        shellExecutor: async (_command, options) => {
+          observedShells.push(options.shell);
+          return { exitCode: 0, stdout: '', stderr: '' };
+        },
+      });
+
+      await runner.runStep({ id: 'configured-default-shell', run: 'echo ok' }, createBaseContext());
+      await runner.runStep(
+        { id: 'step-explicit-shell', run: 'echo ok', shell: 'cmd' },
+        createBaseContext()
+      );
+    });
+
+    expect(observedShells).toEqual(['bash', 'cmd']);
+  });
+
+  it('respects working directory and env for default shell executor', async () => {
+    const workingDirectory = mkdtempSync(join(tmpdir(), 'actions-engine-step-'));
+
+    try {
+      const runner = new StepRunner({
+        workingDirectory,
+        defaultShell: 'bash',
+      });
+
+      const step: Step = {
+        id: 'default-shell',
+        run: 'echo "cwd=$PWD"; echo "from_env=$TAKOS_TEST_ENV"',
+        env: {
+          TAKOS_TEST_ENV: 'from-step',
+        },
+      };
+
+      const result = await runner.runStep(step, createBaseContext());
+
+      expect(result.conclusion).toBe('success');
+      expect(result.outputs.cwd).toBe(workingDirectory);
+      expect(result.outputs.from_env).toBe('from-step');
+    } finally {
+      rmSync(workingDirectory, { recursive: true, force: true });
+    }
+  });
+
+  it('returns failure when default shell executor times out', async () => {
+    const runner = new StepRunner();
+    const step: Step = {
+      id: 'timeout-shell',
+      run: 'node -e "setTimeout(() => {}, 5000)"',
+      'timeout-minutes': 0.001,
+    };
+
+    const result = await runner.runStep(step, createBaseContext());
+
+    expect(result.conclusion).toBe('failure');
+    expect(result.error).toContain('Exit code: 124');
+  });
+
+  it('supports builtin checkout action without a custom resolver', async () => {
+    const runner = new StepRunner();
+    const context = createBaseContext();
+    const step: Step = {
+      id: 'builtin-checkout',
+      uses: 'actions/checkout@v4',
+    };
+
+    const result = await runner.runStep(step, context);
+
+    expect(result.conclusion).toBe('success');
+    expect(result.outputs.path).toBe(context.github.workspace);
+  });
+
+  it('fails explicitly for unsupported default actions', async () => {
+    const runner = new StepRunner();
+    const step: Step = {
+      id: 'unsupported-action',
+      uses: 'actions/cache@v4',
+    };
+
+    const result = await runner.runStep(step, createBaseContext());
+
+    expect(result.conclusion).toBe('failure');
+    expect(result.error).toContain('Unsupported action: actions/cache@v4');
+  });
+});

package/src/__tests__/scheduler/steps-context.test.ts

@@ -0,0 +1,49 @@
+import { describe, expect, it } from 'vitest';
+
+import type { StepResult } from '../../workflow-models.js';
+import {
+  buildStepsContext,
+} from '../../scheduler/job-policy.js';
+
+function createStepResult(overrides: Partial<StepResult> = {}): StepResult {
+  return {
+    id: 'step',
+    status: 'completed',
+    outputs: {},
+    ...overrides,
+  };
+}
+
+describe('steps-context helpers', () => {
+  it('builds context entries from step results and ignores anonymous steps', () => {
+    const firstOutputs = { first: '1' };
+    const secondOutputs = { second: '2' };
+    const stepsContext = buildStepsContext([
+      createStepResult({
+        id: 'build',
+        outputs: firstOutputs,
+        conclusion: 'success',
+      }),
+      createStepResult({
+        id: undefined,
+        outputs: { ignored: 'true' },
+        conclusion: 'failure',
+      }),
+      createStepResult({
+        id: 'build',
+        outputs: secondOutputs,
+        conclusion: 'failure',
+      }),
+    ]);
+
+    expect(stepsContext).toEqual({
+      build: {
+        outputs: { second: '2' },
+        outcome: 'failure',
+        conclusion: 'failure',
+      },
+    });
+    expect(stepsContext.build.outputs).not.toBe(secondOutputs);
+    expect(stepsContext.build.outputs).not.toBe(firstOutputs);
+  });
+});

package/src/constants.ts

@@ -0,0 +1,61 @@
+/**
+ * Centralized constants for the actions-engine package.
+ *
+ * All magic numbers and hard-coded limits are defined here so that they are
+ * easy to find, document, and tune without touching implementation files.
+ */
+
+// ---------------------------------------------------------------------------
+// Parser limits
+// ---------------------------------------------------------------------------
+
+/**
+ * Maximum number of `evaluate()` calls allowed per expression evaluation.
+ * Guards against runaway recursion or adversarial expressions that attempt to
+ * consume unbounded CPU time (e.g. deeply nested bracket accesses).
+ */
+export const MAX_EVALUATE_CALLS = 10_000;
+
+/**
+ * Maximum depth of chained property / bracket accesses (e.g. `a.b.c[0].d`).
+ * Prevents stack overflow and excessive object traversal from malicious or
+ * accidentally deep expressions.
+ */
+export const MAX_PARSE_ACCESS_DEPTH = 128;
+
+/**
+ * Maximum byte length of a JSON string accepted by the `fromJSON()` expression
+ * function. Capped at 1 MB to prevent out-of-memory conditions when an
+ * attacker-controlled value is passed to `JSON.parse`.
+ */
+export const MAX_FROM_JSON_SIZE = 1_048_576; // 1 MB
+
+/**
+ * Maximum byte length of an expression (the content inside `${{ }}`).
+ * Set to 64 KB, which is well above any reasonable expression while still
+ * preventing denial-of-service via extremely long input strings.
+ */
+export const MAX_EXPRESSION_SIZE = 64 * 1024; // 64 KB
+
+// ---------------------------------------------------------------------------
+// Scheduler / step-runner limits
+// ---------------------------------------------------------------------------
+
+/**
+ * Default step timeout in minutes, used when a step does not specify
+ * `timeout-minutes`. Matches the GitHub Actions default of 360 minutes
+ * (6 hours).
+ */
+export const DEFAULT_TIMEOUT_MINUTES = 360;
+
+/**
+ * Multiplier to convert minutes to milliseconds for `setTimeout` calls.
+ */
+export const MINUTES_TO_MS = 60_000;
+
+/**
+ * Maximum size in bytes for GITHUB_ENV / GITHUB_OUTPUT / GITHUB_PATH command
+ * files written by step scripts. Capped at 10 MB to prevent a single step
+ * from exhausting memory when the runner reads these files back.
+ */
+export const MAX_COMMAND_FILE_BYTES = 10 * 1024 * 1024; // 10 MB

package/src/context.ts

@@ -0,0 +1,153 @@
+/**
+ * Context management for workflow execution
+ */
+import type {
+  ExecutionContext,
+  GitHubContext,
+  RunnerContext,
+  InputsContext,
+} from './workflow-models.js';
+
+// ---------------------------------------------------------------------------
+// Base context
+// ---------------------------------------------------------------------------
+
+/**
+ * Context builder options
+ */
+export interface ContextBuilderOptions {
+  /** GitHub context overrides */
+  github?: Partial<GitHubContext>;
+  /** Runner context overrides */
+  runner?: Partial<RunnerContext>;
+  /** Environment variables */
+  env?: Record<string, string>;
+  /** Repository variables */
+  vars?: Record<string, string>;
+  /** Secrets */
+  secrets?: Record<string, string>;
+  /** Workflow dispatch inputs */
+  inputs?: InputsContext;
+}
+
+/**
+ * Create a base execution context
+ */
+export function createBaseContext(
+  options: ContextBuilderOptions = {}
+): ExecutionContext {
+  const os = process.platform;
+  const arch = process.arch;
+
+  const github: GitHubContext = {
+    event_name: 'push',
+    event: {},
+    ref: 'refs/heads/main',
+    ref_name: 'main',
+    sha: '0000000000000000000000000000000000000000',
+    repository: 'owner/repo',
+    repository_owner: 'owner',
+    actor: 'actor',
+    workflow: 'workflow',
+    job: 'job',
+    run_id: '1',
+    run_number: 1,
+    run_attempt: 1,
+    server_url: 'https://github.com',
+    api_url: 'https://api.github.com',
+    graphql_url: 'https://api.github.com/graphql',
+    workspace: '/home/runner/work/repo/repo',
+    action: '',
+    action_path: '',
+    token: '',
+    ...options.github,
+  };
+
+  const osName = os === 'win32' ? 'Windows' as const : os === 'darwin' ? 'macOS' as const : 'Linux' as const;
+  const archMap: Record<string, 'X64' | 'ARM64' | 'ARM' | 'X86'> = { x64: 'X64', arm64: 'ARM64', arm: 'ARM' };
+  const archName = archMap[arch] ?? 'X86';
+
+  const runner: RunnerContext = {
+    name: 'local-runner',
+    os: osName,
+    arch: archName,
+    temp: process.env.RUNNER_TEMP || '/tmp',
+    tool_cache: process.env.RUNNER_TOOL_CACHE || '/opt/hostedtoolcache',
+    debug: process.env.RUNNER_DEBUG || '',
+    ...options.runner,
+  };
+
+  return {
+    github,
+    env: options.env || {},
+    vars: options.vars || {},
+    secrets: options.secrets || {},
+    runner,
+    job: { status: 'success' },
+    steps: {},
+    needs: {},
+    inputs: options.inputs,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Environment variable management
+// ---------------------------------------------------------------------------
+
+const GITHUB_ENV_HEREDOC_PATTERN = /^([a-zA-Z_][a-zA-Z0-9_]*)<<(.+)$/;
+const GITHUB_ENV_SIMPLE_PATTERN = /^([a-zA-Z_][a-zA-Z0-9_]*)=(.*)$/;
+
+/**
+ * Parse GITHUB_ENV file format
+ * Format:
+ *   NAME=value
+ *   or
+ *   NAME<<EOF
+ *   multiline
+ *   value
+ *   EOF
+ */
+export function parseGitHubEnvFile(content: string): Record<string, string> {
+  const env: Record<string, string> = {};
+  const lines = content
+    .split('\n')
+    .map((line) => (line.endsWith('\r') ? line.slice(0, -1) : line));
+  let i = 0;
+
+  while (i < lines.length) {
+    const line = lines[i].trim();
+
+    if (!line || line.startsWith('#')) {
+      i++;
+      continue;
+    }
+
+    // Check for heredoc format: NAME<<DELIMITER
+    const heredocMatch = line.match(GITHUB_ENV_HEREDOC_PATTERN);
+    if (heredocMatch) {
+      const [, name, delimiter] = heredocMatch;
+      const valueLines: string[] = [];
+      i++;
+
+      while (i < lines.length && lines[i] !== delimiter) {
+        valueLines.push(lines[i]);
+        i++;
+      }
+
+      env[name] = valueLines.join('\n');
+      i++; // Skip delimiter line
+      continue;
+    }
+
+    // Simple format: NAME=value
+    const simpleMatch = line.match(GITHUB_ENV_SIMPLE_PATTERN);
+    if (simpleMatch) {
+      const [, name, value] = simpleMatch;
+      env[name] = value;
+    }
+
+    i++;
+  }
+
+  return env;
+}

package/src/index.ts

@@ -0,0 +1,64 @@
+/**
+ * takos-actions-engine
+ * GitHub Actions compatible CI engine
+ */
+
+// Public types
+export type {
+  // Trigger types
+  BranchFilter,
+  PullRequestTriggerConfig,
+  PullRequestEventType,
+  WorkflowDispatchInput,
+  WorkflowDispatchConfig,
+  ScheduleTriggerConfig,
+  RepositoryDispatchConfig,
+  WorkflowCallInput,
+  WorkflowCallOutput,
+  WorkflowCallSecret,
+  WorkflowCallConfig,
+  WorkflowTrigger,
+  // Step / Job / Workflow types
+  Step,
+  MatrixConfig,
+  JobStrategy,
+  ContainerConfig,
+  JobOutputs,
+  PermissionLevel,
+  Permissions,
+  ConcurrencyConfig,
+  JobDefaults,
+  Job,
+  Workflow,
+  // Execution state types
+  RunStatus,
+  Conclusion,
+  StepResult,
+  JobResult,
+  WorkflowResult,
+  // Context types
+  GitHubContext,
+  RunnerContext,
+  JobContext,
+  StepsContext,
+  NeedsContext,
+  StrategyContext,
+  MatrixContext,
+  InputsContext,
+  ExecutionContext,
+  // Parser / scheduler types
+  ParsedWorkflow,
+  DiagnosticSeverity,
+  WorkflowDiagnostic,
+  ExecutionPlan,
+  StepExecutor,
+  ActionResolver,
+} from './workflow-models.js';
+
+// Parser — public API
+export { parseWorkflow } from './parser/workflow.js';
+export { validateWorkflow, type ValidationResult } from './parser/validator.js';
+
+// Scheduler — public API
+export { createExecutionPlan } from './scheduler/job.js';
+