@angular-modernizer/orchestration

Multi-step migration workflows and project analysis helpers for the Angular Modernization Platform.

Overview

The package provides two entry points:

• WorkflowEngine - runs a workflow of tool calls with dependency management, sequential or parallel scheduling, retries, checkpoints and resume. The orchestrate-migration MCP tool is built on it.
• analyzeProject() - loads a project with the analyzer plugin and runs its analysis rules.

The engine does not know any tools itself. Each step names a tool and its arguments, and a ToolExecutor supplied by the caller runs it. In the MCP adapter the executor dispatches to the MCP tools (transform-code, run-build, ...).

Installation

pnpm add @angular-modernizer/orchestration
Copy

Architecture

Caller (orchestrate-migration MCP tool, own code)
    |
WorkflowEngine (scheduling, retries, checkpoints)
    |
ToolExecutor (supplied by the caller)        CheckpointManager (optional, supplied by the caller)
    |
Tools (transform-code, run-build, ...)
Copy

Workflow Engine

Workflow Definition

interface WorkflowDefinition {
  id: string;
  name: string;
  description: string;
  steps: WorkflowStep[];
  strategy?: 'sequential' | 'parallel' | 'auto'; // default 'auto'
  config?: {
    maxParallelSteps?: number; // default 3
    autoCheckpoint?: boolean; // checkpoint after every fifth completed step
    autoRollback?: boolean;
    timeoutMs?: number; // not enforced by the engine
  };
  metadata?: {
    createdBy?: string;
    source?: 'plan-migration' | 'manual' | 'learn-patterns';
    migrationPlan?: unknown;
  };
}

interface WorkflowStep {
  id: string;
  name: string;
  description: string;
  tool: string; // passed to ToolExecutor.executeTool
  args: Record<string, unknown>;
  dependencies: string[]; // may be omitted by JSON callers, treated as []
  estimatedDuration?: number; // used by dry runs (default 100 ms)
  checkpoint?: boolean; // create a checkpoint after this step
  optional?: boolean; // a failure is recorded as 'skipped'
  retry?: { maxAttempts: number; delayMs: number };
}
Copy

Executing a Workflow

import {
  WorkflowEngine,
  type ToolExecutor,
  type WorkflowDefinition,
} from '@angular-modernizer/orchestration';

const executor: ToolExecutor = {
  executeTool: async (toolName, args) => {
    // Dispatch to the tool implementation
    return { toolName, args };
  },
};

const workflow: WorkflowDefinition = {
  id: 'inject-migration',
  name: 'Inject migration',
  description: 'Transform one service, then build',
  strategy: 'sequential',
  steps: [
    {
      id: 'transform',
      name: 'Transform',
      description: 'Constructor injection to inject()',
      tool: 'transform-code',
      args: {
        filePath: 'src/app/user.service.ts',
        transformation: 'constructor-to-inject',
      },
      dependencies: [],
      retry: { maxAttempts: 2, delayMs: 1000 },
    },
    {
      id: 'build',
      name: 'Build',
      description: 'Check the build',
      tool: 'run-build',
      args: { rootPath: '/path/to/project' },
      dependencies: ['transform'],
      checkpoint: true,
    },
  ],
};

const engine = new WorkflowEngine(executor);
const result = await engine.execute(workflow, {
  onStepComplete: (step) => console.log(step.stepId, step.status),
});

console.log(result.status); // 'completed' | 'partial' | 'failed'
console.log(result.metrics); // totalSteps, successfulSteps, failedSteps, skippedSteps, checkpointsCreated
Copy

execute() does not throw for step failures. They are reported in the result: status is completed when no step failed, partial when some steps failed and at least one completed, failed otherwise. errors lists the error of each failed step; an error no step reported (for example a stuck workflow) is listed with the step ID workflow.

Strategies

Failures and Retries

• A step with retry is tried again up to retry.maxAttempts times after the first failure, waiting retry.delayMs before each retry.
• A required step that still fails ends the workflow.
• An optional step that still fails is recorded with status skipped; the workflow goes on.

Checkpoints and Resume

A checkpoint records the results of all completed steps. The engine creates one after each step with checkpoint: true and, with config.autoCheckpoint, after every fifth completed step. With a CheckpointManager each checkpoint is saved, and a later run can resume from it:

import {
  WorkflowEngine,
  type CheckpointManager,
  type WorkflowCheckpoint,
} from '@angular-modernizer/orchestration';

const store = new Map<string, WorkflowCheckpoint>();

const checkpoints: CheckpointManager = {
  saveCheckpoint: async (checkpoint) => {
    store.set(checkpoint.id, checkpoint);
  },
  loadCheckpoint: async (id) => store.get(id) ?? null,
  listCheckpoints: async (workflowId) =>
    [...store.values()].filter((c) => c.workflowId === workflowId),
};

const engine = new WorkflowEngine(executor, checkpoints);
const first = await engine.execute(workflow);

if (first.status !== 'completed' && first.finalCheckpoint) {
  await engine.execute(workflow, {
    resumeFromCheckpoint: first.finalCheckpoint.id,
  });
}
Copy

Steps contained in the checkpoint are not run again. Without a CheckpointManager, resumeFromCheckpoint is ignored. An unknown checkpoint ID fails the workflow.

config.autoRollback triggers a rollback to the last checkpoint when the workflow fails. The engine currently only logs it; files are not restored. Use the rollback-changes MCP tool or the rollback support in @angular-modernizer/core to restore files.

Execution Options

Project Analysis

analyzeProject() creates a Kernel with the AnalyzerPlugin, collects the analysis rules of all registered plugins and runs them concurrently.

import { analyzeProject } from '@angular-modernizer/orchestration';

const results = await analyzeProject({
  projectPath: '/path/to/tsconfig.json',
  config: {},
  options: { deep: true, maxDepth: 3 },
});

for (const result of results) {
  console.log(result.ruleId, result.filePath, result.message);
}
Copy

• projectPath is the path to the project's tsconfig.json; an empty path or a project without source files throws.
• Each rule gets an analysis context whose sourceFile is the first source file of the project; rules that look at the whole project use context.project.
• options is passed to each rule as context.options.
• A rule that throws yields one result with the message Rule execution failed: ... and metadata.error: true; the other rules still run.

Exports

Package Structure

packages/orchestration/
  src/
    index.ts              # public exports
    types.ts              # workflow types
    workflow-engine.ts    # WorkflowEngine, ToolExecutor, CheckpointManager
    project-analyzer.ts   # analyzeProject
  __tests__/
    workflow-engine.test.ts
  package.json
  tsconfig.json
  jest.config.js
  README.md
Copy

Testing

pnpm --filter @angular-modernizer/orchestration test
Copy

The tests cover sequential, parallel and auto execution, checkpoints and resume, retries, dry runs, progress callbacks, result building and steps without dependencies.

Dependencies

• @angular-modernizer/core - Kernel
• @angular-modernizer/api - createPublicApi
• @angular-modernizer/plugin-system - ContextFactory, plugin contracts
• @angular-modernizer/plugin-analyzer - AnalyzerPlugin used by analyzeProject

See Also

• packages/core/README.md - Kernel infrastructure
• packages/plugin-system/README.md - Plugin contracts