refactor(@angular/cli): implement experimental unified run_target facade and strategy dispatcher

clydin · clydin · commit 857cecfd69a0 · 2026-05-19T13:51:12.000-04:00
Introduce the unified `run_target` MCP tool and the underlying builder strategy dispatcher in a dedicated `tools/run-target` subdirectory. This architecture leverages the strategy pattern to delegate Angular CLI target executions (build, test, lint, e2e) to specialized internal strategies, defaulting to a universal `GenericTargetStrategy` fallback.
diff --git a/packages/angular/cli/src/commands/mcp/mcp-server.ts b/packages/angular/cli/src/commands/mcp/mcp-server.ts
@@ -25,6 +25,7 @@ import { DOC_SEARCH_TOOL } from './tools/doc-search';
 import { E2E_TOOL } from './tools/e2e';
 import { ZONELESS_MIGRATION_TOOL } from './tools/onpush-zoneless-migration/zoneless-migration';
 import { LIST_PROJECTS_TOOL } from './tools/projects';
+import { RUN_TARGET_TOOL } from './tools/run-target/run-target';
 import { TEST_TOOL } from './tools/test';
 import { type AnyMcpToolDeclaration, registerTools } from './tools/tool-registry';
 
@@ -49,7 +50,13 @@ const STABLE_TOOLS = [
  * The set of tools that are available but not enabled by default.
  * These tools are considered experimental and may have limitations.
  */
-export const EXPERIMENTAL_TOOLS = [BUILD_TOOL, E2E_TOOL, TEST_TOOL, ...DEVSERVER_TOOLS] as const;
+export const EXPERIMENTAL_TOOLS = [
+  BUILD_TOOL,
+  E2E_TOOL,
+  TEST_TOOL,
+  RUN_TARGET_TOOL,
+  ...DEVSERVER_TOOLS,
+] as const;
 
 /**
  * Experimental tools that are grouped together under a single name.
diff --git a/packages/angular/cli/src/commands/mcp/tools/run-target/generic-target-strategy.ts b/packages/angular/cli/src/commands/mcp/tools/run-target/generic-target-strategy.ts
@@ -0,0 +1,92 @@
+/**
+ * @license
+ * Copyright Google LLC All Rights Reserved.
+ *
+ * Use of this source code is governed by an MIT-style license that can be
+ * found in the LICENSE file at https://angular.dev/license
+ */
+
+import { getCommandErrorLogs } from '../../utils';
+import type { McpToolContext } from '../tool-registry';
+import type { TargetStrategy } from './strategy';
+import type { RunTargetOutput, StrategyExecutionContext } from './types';
+
+const BUILT_IN_COMMANDS = new Set([
+  'build',
+  'test',
+  'e2e',
+  'serve',
+  'deploy',
+  'extract-i18n',
+  'lint',
+]);
+
+export class GenericTargetStrategy implements TargetStrategy {
+  canHandle(target: string, builder?: string): boolean {
+    return true; // Universal fallback strategy
+  }
+
+  async execute(
+    input: StrategyExecutionContext,
+    context: McpToolContext,
+  ): Promise<RunTargetOutput> {
+    if (input.target === 'serve' || input.options?.['watch'] === true) {
+      throw new Error(
+        `Watch mode execution (serve target or watch option) is not yet supported by 'run_target'. ` +
+          `Please use the legacy 'devserver.start' / 'devserver.wait_for_build' tools instead.`,
+      );
+    }
+
+    const args: string[] = [];
+    if (BUILT_IN_COMMANDS.has(input.target)) {
+      args.push(input.target, input.projectName);
+    } else {
+      args.push('run', `${input.projectName}:${input.target}`);
+    }
+
+    if (input.configuration) {
+      args.push('-c', input.configuration);
+    }
+
+    let options = input.options;
+    if (input.target === 'test') {
+      options = {
+        ...options,
+        watch: false,
+      };
+    }
+
+    if (options) {
+      for (const [key, value] of Object.entries(options)) {
+        if (!/^[a-zA-Z0-9-_]+$/.test(key)) {
+          throw new Error(
+            `Invalid option key: '${key}'. Option keys must be alphanumeric, hyphens, or underscores.`,
+          );
+        }
+
+        if (typeof value === 'boolean') {
+          args.push(value ? `--${key}` : `--no-${key}`);
+        } else if (Array.isArray(value)) {
+          for (const item of value) {
+            args.push(`--${key}=${item}`);
+          }
+        } else if (value !== null && value !== undefined) {
+          args.push(`--${key}=${value}`);
+        }
+      }
+    }
+
+    let status: 'success' | 'failure' = 'success';
+    let logs: string[];
+
+    try {
+      const result = await context.host.executeNgCommand(args, { cwd: input.workspacePath });
+      logs = result.logs;
+    } catch (e) {
+      status = 'failure';
+      logs = getCommandErrorLogs(e);
+    }
+
+    return { status, logs };
+  }
+}
diff --git a/packages/angular/cli/src/commands/mcp/tools/run-target/run-target.ts b/packages/angular/cli/src/commands/mcp/tools/run-target/run-target.ts
@@ -0,0 +1,70 @@
+/**
+ * @license
+ * Copyright Google LLC All Rights Reserved.
+ *
+ * Use of this source code is governed by an MIT-style license that can be
+ * found in the LICENSE file at https://angular.dev/license
+ */
+
+import { createStructuredContentOutput } from '../../utils';
+import { resolveWorkspaceAndProject } from '../../workspace-utils';
+import { type McpToolContext, declareTool } from '../tool-registry';
+import { GenericTargetStrategy } from './generic-target-strategy';
+import type { TargetStrategy } from './strategy';
+import { type RunTargetInput, runTargetInputSchema, runTargetOutputSchema } from './types';
+
+const FALLBACK_STRATEGY = new GenericTargetStrategy();
+const STRATEGIES: TargetStrategy[] = [];
+
+export async function runTarget(input: RunTargetInput, context: McpToolContext) {
+  const { workspace, workspacePath, projectName } = await resolveWorkspaceAndProject({
+    host: context.host,
+    server: context.server,
+    workspacePathInput: input.workspace,
+    projectNameInput: input.project,
+    mcpWorkspace: context.workspace,
+  });
+
+  const targetDefinition = workspace.projects.get(projectName)?.targets.get(input.target);
+  const builder = targetDefinition?.builder;
+
+  const strategy = STRATEGIES.find((s) => s.canHandle(input.target, builder)) ?? FALLBACK_STRATEGY;
+
+  const result = await strategy.execute(
+    {
+      workspacePath,
+      projectName,
+      target: input.target,
+      configuration: input.configuration,
+      options: input.options,
+    },
+    context,
+  );
+
+  return createStructuredContentOutput(result);
+}
+
+export const RUN_TARGET_TOOL = declareTool({
+  name: 'run_target',
+  title: 'Run Project Target',
+  description: `
+<Purpose>
+Executes a configured target (such as build, test, lint, e2e) for an Angular project.
+This is the single, unified interface for executing all project tasks natively.
+</Purpose>
+<Use Cases>
+* Building an application or library.
+* Running unit tests, E2E tests, or linters.
+* Deploying or running custom workspace targets discovered via 'list_projects'.
+</Use Cases>
+<Operational Notes>
+* Mandatory Discovery: You MUST discover available project targets by calling 'list_projects' first.
+* Watch mode (serve target or watch options) is NOT yet supported in this version of run_target.
+  You MUST use the legacy 'devserver.*' tools for background server lifecycles.
+</Operational Notes>`,
+  isReadOnly: false,
+  isLocalOnly: true,
+  inputSchema: runTargetInputSchema.shape,
+  outputSchema: runTargetOutputSchema.shape,
+  factory: (context) => (input) => runTarget(input, context),
+});
diff --git a/packages/angular/cli/src/commands/mcp/tools/run-target/run-target_spec.ts b/packages/angular/cli/src/commands/mcp/tools/run-target/run-target_spec.ts
@@ -0,0 +1,148 @@
+/**
+ * @license
+ * Copyright Google LLC All Rights Reserved.
+ *
+ * Use of this source code is governed by an MIT-style license that can be
+ * found in the LICENSE file at https://angular.dev/license
+ */
+
+import { CommandError } from '../../host';
+import type { MockHost } from '../../testing/mock-host';
+import {
+  type MockMcpToolContext,
+  addProjectToWorkspace,
+  createMockContext,
+} from '../../testing/test-utils';
+import { runTarget } from './run-target';
+
+describe('Run Target Tool', () => {
+  let mockHost: MockHost;
+  let mockContext: MockMcpToolContext;
+
+  beforeEach(() => {
+    const mock = createMockContext();
+    mockHost = mock.host;
+    mockContext = mock.context;
+    addProjectToWorkspace(mock.projects, 'my-app');
+  });
+
+  it('should construct the command correctly with target and default project', async () => {
+    mockContext.workspace.extensions['defaultProject'] = 'my-app';
+    await runTarget({ target: 'build' }, mockContext);
+    expect(mockHost.executeNgCommand).toHaveBeenCalledWith(['build', 'my-app'], { cwd: '/test' });
+  });
+
+  it('should construct the command correctly with a specified project', async () => {
+    addProjectToWorkspace(mockContext.workspace.projects, 'my-lib');
+    await runTarget({ project: 'my-lib', target: 'lint' }, mockContext);
+    expect(mockHost.executeNgCommand).toHaveBeenCalledWith(['lint', 'my-lib'], { cwd: '/test' });
+  });
+
+  it('should construct the command correctly with configuration', async () => {
+    mockContext.workspace.extensions['defaultProject'] = 'my-app';
+    await runTarget({ target: 'build', configuration: 'production' }, mockContext);
+    expect(mockHost.executeNgCommand).toHaveBeenCalledWith(
+      ['build', 'my-app', '-c', 'production'],
+      {
+        cwd: '/test',
+      },
+    );
+  });
+
+  it('should route custom targets via ng run command syntax', async () => {
+    mockContext.workspace.extensions['defaultProject'] = 'my-app';
+    await runTarget({ target: 'storybook', configuration: 'docs' }, mockContext);
+    expect(mockHost.executeNgCommand).toHaveBeenCalledWith(
+      ['run', 'my-app:storybook', '-c', 'docs'],
+      { cwd: '/test' },
+    );
+  });
+
+  it('should map boolean options correctly to CLI flags', async () => {
+    mockContext.workspace.extensions['defaultProject'] = 'my-app';
+    await runTarget({ target: 'lint', options: { fix: true, quiet: false } }, mockContext);
+    expect(mockHost.executeNgCommand).toHaveBeenCalledWith(
+      ['lint', 'my-app', '--fix', '--no-quiet'],
+      { cwd: '/test' },
+    );
+  });
+
+  it('should map string and number options correctly to CLI flags and auto-inject no-watch', async () => {
+    mockContext.workspace.extensions['defaultProject'] = 'my-app';
+    await runTarget(
+      { target: 'test', options: { browsers: 'ChromeHeadless', timeout: 5000 } },
+      mockContext,
+    );
+    expect(mockHost.executeNgCommand).toHaveBeenCalledWith(
+      ['test', 'my-app', '--browsers=ChromeHeadless', '--timeout=5000', '--no-watch'],
+      { cwd: '/test' },
+    );
+  });
+
+  it('should map array options correctly as multiple occurrences of the flag', async () => {
+    mockContext.workspace.extensions['defaultProject'] = 'my-app';
+    await runTarget({ target: 'lint', options: { include: ['a', 'b'] } }, mockContext);
+    expect(mockHost.executeNgCommand).toHaveBeenCalledWith(
+      ['lint', 'my-app', '--include=a', '--include=b'],
+      { cwd: '/test' },
+    );
+  });
+
+  it('should automatically inject no-watch for test target even if no options provided', async () => {
+    mockContext.workspace.extensions['defaultProject'] = 'my-app';
+    await runTarget({ target: 'test' }, mockContext);
+    expect(mockHost.executeNgCommand).toHaveBeenCalledWith(['test', 'my-app', '--no-watch'], {
+      cwd: '/test',
+    });
+  });
+
+  it('should throw an error if option key is malformed (contains whitespace/special chars)', async () => {
+    mockContext.workspace.extensions['defaultProject'] = 'my-app';
+    await expectAsync(
+      runTarget({ target: 'lint', options: { 'fix --danger': true } }, mockContext),
+    ).toBeRejectedWithError(/Invalid option key: 'fix --danger'/);
+  });
+
+  it('should handle a successful execution and return logs', async () => {
+    const executionLogs = ['Linting complete', 'All rules passed!'];
+    mockHost.executeNgCommand.and.resolveTo({
+      logs: executionLogs,
+    });
+
+    const { structuredContent } = await runTarget(
+      { project: 'my-app', target: 'lint' },
+      mockContext,
+    );
+
+    expect(structuredContent.status).toBe('success');
+    expect(structuredContent.logs).toEqual(executionLogs);
+  });
+
+  it('should handle a failed execution and capture command errors', async () => {
+    const executionLogs = ['Error: Rule violation found.'];
+    const error = new CommandError('Lint failed', executionLogs, 1);
+    mockHost.executeNgCommand.and.rejectWith(error);
+
+    const { structuredContent } = await runTarget(
+      { project: 'my-app', target: 'lint' },
+      mockContext,
+    );
+
+    expect(structuredContent.status).toBe('failure');
+    expect(structuredContent.logs).toEqual([...executionLogs, 'Lint failed']);
+  });
+
+  it('should throw an error if attempting to run the serve target', async () => {
+    mockContext.workspace.extensions['defaultProject'] = 'my-app';
+    await expectAsync(runTarget({ target: 'serve' }, mockContext)).toBeRejectedWithError(
+      /Watch mode execution.*is not yet supported/,
+    );
+  });
+
+  it('should throw an error if attempting to run a target with watch option true', async () => {
+    mockContext.workspace.extensions['defaultProject'] = 'my-app';
+    await expectAsync(
+      runTarget({ target: 'build', options: { watch: true } }, mockContext),
+    ).toBeRejectedWithError(/Watch mode execution.*is not yet supported/);
+  });
+});
diff --git a/packages/angular/cli/src/commands/mcp/tools/run-target/strategy.ts b/packages/angular/cli/src/commands/mcp/tools/run-target/strategy.ts
@@ -0,0 +1,18 @@
+/**
+ * @license
+ * Copyright Google LLC All Rights Reserved.
+ *
+ * Use of this source code is governed by an MIT-style license that can be
+ * found in the LICENSE file at https://angular.dev/license
+ */
+
+import type { McpToolContext } from '../tool-registry';
+import type { RunTargetOutput, StrategyExecutionContext } from './types';
+
+export interface TargetStrategy {
+  /** Whether this strategy is responsible for handling the given target/builder */
+  canHandle(target: string, builder?: string): boolean;
+
+  /** Executes the target using this strategy */
+  execute(input: StrategyExecutionContext, context: McpToolContext): Promise<RunTargetOutput>;
+}
diff --git a/packages/angular/cli/src/commands/mcp/tools/run-target/types.ts b/packages/angular/cli/src/commands/mcp/tools/run-target/types.ts
