@angular/cli 21.0.0-next.1 → 21.0.0-next.3

package/src/commands/mcp/tools/modernize.js

@@ -59,7 +59,9 @@ const modernizeInputSchema = zod_1.z.object({
     // Casting to [string, ...string[]] since the enum definition requires a nonempty array.
     transformations: zod_1.z
         .array(zod_1.z.enum(TRANSFORMATIONS.map((t) => t.name)))
-        .optional(),
+        .optional()
+        .describe('A list of specific transformations to get instructions for. ' +
+        'If omitted, general guidance is provided.'),
 });
 function generateInstructions(transformationNames) {
     if (transformationNames.length === 0) {
@@ -97,27 +99,36 @@ async function runModernization(input) {
 exports.MODERNIZE_TOOL = (0, tool_registry_1.declareTool)({
     name: 'modernize',
     title: 'Modernize Angular Code',
-    description: '<Purpose>\n' +
-        'This tool modernizes Angular code by applying the latest best practices and syntax improvements, ' +
-        'ensuring it is idiomatic, readable, and maintainable.\n\n' +
-        '</Purpose>\n' +
-        '<Use Cases>\n' +
-        '* After generating new code: Run this tool immediately after creating new Angular components, directives, ' +
-        'or services to ensure they adhere to modern standards.\n' +
-        '* On existing code: Apply to existing TypeScript files (.ts) and Angular templates (.html) to update ' +
-        'them with the latest features, such as the new built-in control flow syntax.\n\n' +
-        '* When the user asks for a specific transformation: When the transformation list is populated, ' +
-        'these specific ones will be ran on the inputs.\n' +
-        '</Use Cases>\n' +
-        '<Transformations>\n' +
-        TRANSFORMATIONS.map((t) => `* ${t.name}: ${t.description}`).join('\n') +
-        '\n</Transformations>\n',
+    description: `
+<Purpose>
+Provides instructions and commands for modernizing Angular code to align with the latest best
+practices and syntax. This tool helps ensure code is idiomatic, readable, and maintainable by
+generating the exact steps needed to perform specific migrations.
+</Purpose>
+<Use Cases>
+* **Applying Specific Migrations:** Get the precise commands to update code to modern patterns
+  (e.g., selecting 'control-flow-migration' to replace *ngIf with @if).
+* **Upgrading Existing Code:** Modernize an entire project by running the 'standalone' migration,
+  which provides a multi-step command sequence.
+* **Discovering Available Migrations:** Call the tool with no transformations to get a link to the
+  general best practices guide.
+</Use Cases>
+<Operational Notes>
+* **Execution:** This tool **provides instructions**, which you **MUST** then execute as shell commands.
+  It does not modify code directly.
+* **Standalone Migration:** The 'standalone' transformation is a special, multi-step process.
+  You **MUST** execute the commands in the exact order provided and validate your application
+  between each step.
+* **Transformation List:** The following transformations are available:
+${TRANSFORMATIONS.map((t) => `  * ${t.name}: ${t.description}`).join('\n')}
+</Operational Notes>`,
     inputSchema: modernizeInputSchema.shape,
     outputSchema: {
         instructions: zod_1.z
             .array(zod_1.z.string())
             .optional()
-            .describe('A list of instructions on how to run the migrations.'),
+            .describe('A list of instructions and shell commands to run the requested modernizations. ' +
+            'Each string in the array is a separate step or command.'),
     },
     isLocalOnly: true,
     isReadOnly: true,

package/src/commands/mcp/tools/onpush-zoneless-migration/analyze_for_unsupported_zone_uses.d.ts

@@ -0,0 +1,17 @@
+/**
+ * @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 { ImportSpecifier, Node, SourceFile } from 'typescript';
+import { MigrationResponse } from './types';
+export declare function analyzeForUnsupportedZoneUses(sourceFile: SourceFile): Promise<MigrationResponse | null>;
+/**
+ * Finds usages of `NgZone` that are not supported in zoneless applications.
+ * @param sourceFile The source file to check.
+ * @param ngZoneImport The import specifier for `NgZone`.
+ * @returns A list of nodes that are unsupported `NgZone` usages.
+ */
+export declare function findUnsupportedZoneUsages(sourceFile: SourceFile, ngZoneImport: ImportSpecifier): Promise<Node[]>;

package/src/commands/mcp/tools/onpush-zoneless-migration/analyze_for_unsupported_zone_uses.js

@@ -0,0 +1,61 @@
+"use strict";
+/**
+ * @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
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.analyzeForUnsupportedZoneUses = analyzeForUnsupportedZoneUses;
+exports.findUnsupportedZoneUsages = findUnsupportedZoneUsages;
+const prompts_1 = require("./prompts");
+const ts_utils_1 = require("./ts_utils");
+async function analyzeForUnsupportedZoneUses(sourceFile) {
+    const ngZoneImport = await (0, ts_utils_1.getImportSpecifier)(sourceFile, '@angular/core', 'NgZone');
+    if (!ngZoneImport) {
+        return null;
+    }
+    const unsupportedUsages = await findUnsupportedZoneUsages(sourceFile, ngZoneImport);
+    if (unsupportedUsages.length === 0) {
+        return null;
+    }
+    const locations = unsupportedUsages.map((node) => {
+        const { line, character } = sourceFile.getLineAndCharacterOfPosition(node.getStart());
+        return `line ${line + 1}, character ${character + 1}: ${node.getText()}`;
+    });
+    return (0, prompts_1.createUnsupportedZoneUsagesMessage)(locations, sourceFile.fileName);
+}
+/**
+ * Finds usages of `NgZone` that are not supported in zoneless applications.
+ * @param sourceFile The source file to check.
+ * @param ngZoneImport The import specifier for `NgZone`.
+ * @returns A list of nodes that are unsupported `NgZone` usages.
+ */
+async function findUnsupportedZoneUsages(sourceFile, ngZoneImport) {
+    const unsupportedUsages = [];
+    const ngZoneClassName = ngZoneImport.name.text;
+    const staticMethods = new Set([
+        'isInAngularZone',
+        'assertInAngularZone',
+        'assertNotInAngularZone',
+    ]);
+    const instanceMethods = new Set(['onMicrotaskEmpty', 'onStable']);
+    const ts = await (0, ts_utils_1.loadTypescript)();
+    ts.forEachChild(sourceFile, function visit(node) {
+        if (ts.isPropertyAccessExpression(node)) {
+            const propertyName = node.name.text;
+            const expressionText = node.expression.getText(sourceFile);
+            // Static: NgZone.method()
+            if (expressionText === ngZoneClassName && staticMethods.has(propertyName)) {
+                unsupportedUsages.push(node);
+            }
+            // Instance: zone.method() or this.zone.method()
+            if (instanceMethods.has(propertyName)) {
+                unsupportedUsages.push(node);
+            }
+        }
+        ts.forEachChild(node, visit);
+    });
+    return unsupportedUsages;
+}

package/src/commands/mcp/tools/onpush-zoneless-migration/migrate_single_file.d.ts

@@ -0,0 +1,12 @@
+/**
+ * @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 { RequestHandlerExtra } from '@modelcontextprotocol/sdk/shared/protocol';
+import { ServerNotification, ServerRequest } from '@modelcontextprotocol/sdk/types';
+import type { SourceFile } from 'typescript';
+import { MigrationResponse } from './types';
+export declare function migrateSingleFile(sourceFile: SourceFile, extras: RequestHandlerExtra<ServerRequest, ServerNotification>): Promise<MigrationResponse | null>;

package/src/commands/mcp/tools/onpush-zoneless-migration/migrate_single_file.js

@@ -0,0 +1,72 @@
+"use strict";
+/**
+ * @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
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.migrateSingleFile = migrateSingleFile;
+const analyze_for_unsupported_zone_uses_1 = require("./analyze_for_unsupported_zone_uses");
+const migrate_test_file_1 = require("./migrate_test_file");
+const prompts_1 = require("./prompts");
+const send_debug_message_1 = require("./send_debug_message");
+const ts_utils_1 = require("./ts_utils");
+async function migrateSingleFile(sourceFile, extras) {
+    const testBedSpecifier = await (0, ts_utils_1.getImportSpecifier)(sourceFile, '@angular/core/testing', 'TestBed');
+    const isTestFile = sourceFile.fileName.endsWith('.spec.ts') || !!testBedSpecifier;
+    if (isTestFile) {
+        return (0, migrate_test_file_1.migrateTestFile)(sourceFile);
+    }
+    const unsupportedZoneUseResponse = await (0, analyze_for_unsupported_zone_uses_1.analyzeForUnsupportedZoneUses)(sourceFile);
+    if (unsupportedZoneUseResponse) {
+        return unsupportedZoneUseResponse;
+    }
+    let detectedStrategy;
+    let hasComponentDecorator = false;
+    const componentSpecifier = await (0, ts_utils_1.getImportSpecifier)(sourceFile, '@angular/core', 'Component');
+    if (!componentSpecifier) {
+        (0, send_debug_message_1.sendDebugMessage)(`No component decorator found in file: ${sourceFile.fileName}`, extras);
+        return null;
+    }
+    const ts = await (0, ts_utils_1.loadTypescript)();
+    ts.forEachChild(sourceFile, function visit(node) {
+        if (detectedStrategy) {
+            return; // Already found, no need to traverse further
+        }
+        if (ts.isDecorator(node) && ts.isCallExpression(node.expression)) {
+            const callExpr = node.expression;
+            if (callExpr.expression.getText(sourceFile) === 'Component') {
+                hasComponentDecorator = true;
+                if (callExpr.arguments.length > 0 && ts.isObjectLiteralExpression(callExpr.arguments[0])) {
+                    const componentMetadata = callExpr.arguments[0];
+                    for (const prop of componentMetadata.properties) {
+                        if (ts.isPropertyAssignment(prop) &&
+                            prop.name.getText(sourceFile) === 'changeDetection') {
+                            if (ts.isPropertyAccessExpression(prop.initializer) &&
+                                prop.initializer.expression.getText(sourceFile) === 'ChangeDetectionStrategy') {
+                                const strategy = prop.initializer.name.text;
+                                if (strategy === 'OnPush' || strategy === 'Default') {
+                                    detectedStrategy = strategy;
+                                    return;
+                                }
+                            }
+                        }
+                    }
+                }
+            }
+        }
+        ts.forEachChild(node, visit);
+    });
+    if (!hasComponentDecorator ||
+        // component uses OnPush. We don't have anything more to do here.
+        detectedStrategy === 'OnPush' ||
+        // Explicit default strategy, assume there's a reason for it (already migrated, or is a library that hosts Default components) and skip.
+        detectedStrategy === 'Default') {
+        (0, send_debug_message_1.sendDebugMessage)(`Component decorator found with strategy: ${detectedStrategy} in file: ${sourceFile.fileName}. Skipping migration for file.`, extras);
+        return null;
+    }
+    // Component decorator found, but no change detection strategy.
+    return (0, prompts_1.generateZonelessMigrationInstructionsForComponent)(sourceFile.fileName);
+}

package/src/commands/mcp/tools/onpush-zoneless-migration/migrate_test_file.d.ts

@@ -0,0 +1,11 @@
+/**
+ * @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 { SourceFile } from 'typescript';
+import { MigrationResponse } from './types';
+export declare function migrateTestFile(sourceFile: SourceFile): Promise<MigrationResponse | null>;
+export declare function searchForGlobalZoneless(startPath: string): Promise<boolean>;

package/src/commands/mcp/tools/onpush-zoneless-migration/migrate_test_file.js

@@ -0,0 +1,105 @@
+"use strict";
+/**
+ * @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
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.migrateTestFile = migrateTestFile;
+exports.searchForGlobalZoneless = searchForGlobalZoneless;
+const fs = __importStar(require("node:fs"));
+const promises_1 = require("node:fs/promises");
+const node_path_1 = require("node:path");
+const prompts_1 = require("./prompts");
+const ts_utils_1 = require("./ts_utils");
+async function migrateTestFile(sourceFile) {
+    const ts = await (0, ts_utils_1.loadTypescript)();
+    // Check if tests use zoneless either by default through `initTestEnvironment` or by explicitly calling `provideZonelessChangeDetection`.
+    let testsUseZonelessChangeDetection = await searchForGlobalZoneless(sourceFile.fileName);
+    if (!testsUseZonelessChangeDetection) {
+        ts.forEachChild(sourceFile, function visit(node) {
+            if (ts.isCallExpression(node) &&
+                node.expression.getText(sourceFile) === 'provideZonelessChangeDetection') {
+                testsUseZonelessChangeDetection = true;
+                return;
+            }
+            ts.forEachChild(node, visit);
+        });
+    }
+    if (!testsUseZonelessChangeDetection) {
+        // Tests do not use zoneless, so we provide instructions to set it up.
+        return (0, prompts_1.createProvideZonelessForTestsSetupPrompt)(sourceFile.fileName);
+    }
+    // At this point, tests are using zoneless, so we look for any explicit uses of `provideZoneChangeDetection` that need to be fixed.
+    return (0, prompts_1.createFixResponseForZoneTests)(sourceFile);
+}
+async function searchForGlobalZoneless(startPath) {
+    const angularJsonDir = findAngularJsonDir(startPath);
+    if (!angularJsonDir) {
+        // Cannot determine project root, fallback to original behavior or assume false.
+        // For now, let's assume no global setup if angular.json is not found.
+        return false;
+    }
+    try {
+        const files = (0, promises_1.glob)(`${angularJsonDir}/**/*.ts`);
+        for await (const file of files) {
+            const content = fs.readFileSync(file, 'utf-8');
+            if (content.includes('initTestEnvironment') &&
+                content.includes('provideZonelessChangeDetection')) {
+                return true;
+            }
+        }
+    }
+    catch (e) {
+        return false;
+    }
+    return false;
+}
+function findAngularJsonDir(startDir) {
+    let currentDir = startDir;
+    while (true) {
+        if (fs.existsSync((0, node_path_1.join)(currentDir, 'angular.json'))) {
+            return currentDir;
+        }
+        const parentDir = (0, node_path_1.dirname)(currentDir);
+        if (parentDir === currentDir) {
+            return null;
+        }
+        currentDir = parentDir;
+    }
+}

package/src/commands/mcp/tools/onpush-zoneless-migration/prompts.d.ts

@@ -0,0 +1,15 @@
+/**
+ * @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 { SourceFile } from 'typescript';
+import { MigrationResponse } from './types';
+export declare function createProvideZonelessForTestsSetupPrompt(testFilePath: string): MigrationResponse;
+export declare function createUnsupportedZoneUsagesMessage(usages: string[], filePath: string): MigrationResponse;
+export declare function generateZonelessMigrationInstructionsForComponent(filePath: string): MigrationResponse;
+export declare function createTestDebuggingGuideForNonActionableInput(fileOrDirPath: string): MigrationResponse;
+export declare function createFixResponseForZoneTests(sourceFile: SourceFile): Promise<MigrationResponse | null>;
+export declare function createResponse(text: string): MigrationResponse;

package/src/commands/mcp/tools/onpush-zoneless-migration/prompts.js

@@ -0,0 +1,236 @@
+"use strict";
+/**
+ * @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
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createProvideZonelessForTestsSetupPrompt = createProvideZonelessForTestsSetupPrompt;
+exports.createUnsupportedZoneUsagesMessage = createUnsupportedZoneUsagesMessage;
+exports.generateZonelessMigrationInstructionsForComponent = generateZonelessMigrationInstructionsForComponent;
+exports.createTestDebuggingGuideForNonActionableInput = createTestDebuggingGuideForNonActionableInput;
+exports.createFixResponseForZoneTests = createFixResponseForZoneTests;
+exports.createResponse = createResponse;
+const ts_utils_1 = require("./ts_utils");
+/* eslint-disable max-len */
+function createProvideZonelessForTestsSetupPrompt(testFilePath) {
+    const text = `You are an expert Angular developer assisting with a migration to zoneless. Your task is to update the test file at \`${testFilePath}\` to enable zoneless change detection and identify tests that are not yet compatible.
+
+    Follow these instructions precisely.
+
+    ### Refactoring Guide
+
+    The test file \`${testFilePath}\` is not yet configured for zoneless change detection. You need to enable it for the entire test suite and then identify which specific tests fail.
+
+    #### Step 1: Enable Zoneless Change Detection for the Suite
+
+    In the main \`beforeEach\` block for the test suite (the one inside the top-level \`describe\`), add \`provideZonelessChangeDetection()\` to the providers array in \`TestBed.configureTestingModule\`.
+
+    *   If there is already an import from \`@angular/core\`, add \`provideZonelessChangeDetection\` to the existing import.
+    *   Otherwise, add a new import statement for \`provideZonelessChangeDetection\` from \`@angular/core\`.
+
+    \`\`\`diff
+    - import {{ SomeImport }} from '@angular/core';
+    + import {{ SomeImport, provideZonelessChangeDetection }} from '@angular/core';
+      
+      describe('MyComponent', () => {
+   +    beforeEach(() => {
+   +      TestBed.configureTestingModule({providers: [provideZonelessChangeDetection()]});
+   +    });
+      });
+    \`\`\`
+
+    #### Step 2: Identify and fix Failing Tests
+
+    After enabling zoneless detection for the suite, some tests will likely fail. Your next task is to identify these failing tests and fix them.
+
+    ${testDebuggingGuideText(testFilePath)}
+    8.  **DO** add \`provideZonelessChangeDetection()\` _once_ to the top-most \`describe\` in a \`beforeEach\` block as instructed in Step 1.
+    9.  **DO** run the tests after adding \`provideZonelessChangeDetection\` to see which ones fail. **DO NOT** make assumptions about which tests will might fail.
+
+    ### Final Step
+    After you have applied all the required changes and followed all the rules, consult this tool again for the next steps in the migration process.`;
+    return createResponse(text);
+}
+function createUnsupportedZoneUsagesMessage(usages, filePath) {
+    const text = `You are an expert Angular developer assisting with a migration to zoneless. Your task is to refactor the component in ${filePath} to remove unsupported NgZone APIs.
+
+The component uses NgZone APIs that are incompatible with zoneless applications. The only permitted NgZone APIs are \`NgZone.run\` and \`NgZone.runOutsideAngular\`.
+
+The following usages are unsupported and must be fixed:
+${usages.map((usage) => `- ${usage}`).join('\n')}
+
+Follow these instructions precisely to refactor the code.
+
+### Refactoring Guide
+
+#### 1. APIs to Remove (No Replacement)
+The following methods have no replacement in a zoneless context and must be removed entirely:
+- \`NgZone.assertInAngularZone\`
+- \`NgZone.assertNotInAngularZone\`
+- \`NgZone.isInAngularZone\`
+
+#### 2. APIs to Replace
+The \`onMicrotaskEmpty\` and \`onStable\` observables must be replaced with modern Angular APIs.
+
+- **For single-event subscriptions** (e.g., using \`.pipe(take(1))\` or \`.pipe(first())\`), use \`afterNextRender\` from \`@angular/core\`.
+
+  \`\`\`diff
+  - this.zone.onMicrotaskEmpty.pipe(take(1)).subscribe(() => {});
+  - this.zone.onStable.pipe(take(1)).subscribe(() => {});
+  + import { afterNextRender, Injector } from '@angular/core';
+  + afterNextRender(() => {}, {injector: this.injector});
+  \`\`\`
+
+- **For continuous subscriptions**, use \`afterEveryRender\` from \`@angular/core\`.
+
+  \`\`\`diff
+  - this.zone.onMicrotaskEmpty.subscribe(() => {});
+  - this.zone.onStable.subscribe(() => {});
+  + import { afterEveryRender, Injector } from '@angular/core';
+  + afterEveryRender(() => {}, {injector: this.injector});
+  \`\`\`
+
+- If the code checks \`this.zone.isStable\` before subscribing, you can remove the \`isStable\` check. \`afterNextRender\` handles this case correctly.
+
+### IMPORTANT: Rules and Constraints
+You must follow these rules without exception:
+1.  **DO NOT** make any changes to the component that are unrelated to removing the unsupported NgZone APIs listed above.
+2.  **DO NOT** remove or modify usages of \`NgZone.run\` or \`NgZone.runOutsideAngular\`. These are still required.
+3.  **DO** ensure that you replace \`onMicrotaskEmpty\` and \`onStable\` with the correct replacements (\`afterNextRender\` or \`afterEveryRender\`) as described in the guide.
+4.  **DO** add the necessary imports for \`afterNextRender\`, \`afterEveryRender\`, and \`Injector\` when you use them.
+
+### Final Step
+After you have applied all the required changes and followed all the rules, consult this tool again for the next steps in the migration process.
+`;
+    return createResponse(text);
+}
+function generateZonelessMigrationInstructionsForComponent(filePath) {
+    const text = `You are an expert Angular developer assisting with a migration to zoneless. Your task is to refactor the component in \`${filePath}\` to be compatible with zoneless change detection by ensuring Angular is notified of all state changes that affect the view.
+
+  The component does not currently use a change detection strategy, which means it may rely on Zone.js. To prepare it for zoneless, you must manually trigger change detection when its state changes.
+
+  Follow these instructions precisely.
+
+  ### Refactoring Guide
+
+  #### Step 1: Identify and Refactor State
+  Your primary goal is to ensure that every time a component property used in the template is updated, Angular knows it needs to run change detection.
+
+  1.  **Identify Properties**: Find all component properties that are read by the template.
+  2.  **Choose a Strategy**: For each property identified, choose one of the following refactoring strategies:
+    *   **(Preferred) Convert to Signal**: The best approach is to convert the property to an Angular Signal. This is the most idiomatic and future-proof way to handle state in zoneless applications.
+    *   **(Alternative) Use \`markForCheck()\`**: If converting to a signal is too complex or would require extensive refactoring, you can instead inject \`ChangeDetectorRef\` and call \`this.cdr.markForCheck()\` immediately after the property is updated.
+
+  #### Step 2: Add \`ChangeDetectionStrategy.Default\`
+  After you have refactored all necessary properties, you must update the component's decorator to explicitly set the change detection strategy.
+
+  1.  Add \`ChangeDetectionStrategy\` to the import from \`@angular/core\`.
+  2.  In the \`@Component\` decorator, add the property \`changeDetection: ChangeDetectionStrategy.Default\`.
+  3.  Add a \`// TODO\` comment above this line explaining that the component should be fully migrated to \`OnPush\` after the application has been tested with these changes.
+
+  Example:
+  \`\`\`typescript
+  @Component({
+    ...
+    // TODO: This component has been partially migrated to be zoneless-compatible.
+    // After testing, this should be updated to ChangeDetectionStrategy.OnPush.
+    changeDetection: ChangeDetectionStrategy.Default,
+  })
+  \`\`\`
+
+  ### IMPORTANT: Rules and Constraints
+  You must follow these rules without exception:
+  1.  **DO** apply one of the two refactoring strategies (signals or \`markForCheck()\`) for all relevant component properties.
+  2.  **DO** add \`changeDetection: ChangeDetectionStrategy.Default\` with the specified TODO comment as the final code change.
+  3.  **DO NOT** use \`ChangeDetectionStrategy.OnPush\`. This will be the next step in the migration, but it is not part of this task.
+  4.  **DO NOT** modify properties that are already signals or are used with the \`async\` pipe in the template, as they are already zoneless-compatible.
+  5.  **DO NOT** make any changes to files other than the component file at \`${filePath}\` and its direct template/style files if necessary.
+
+  ### Final Step
+  After you have applied all the required changes and followed all the rules, consult this tool again for the next steps in the migration process.`;
+    return createResponse(text);
+}
+function createTestDebuggingGuideForNonActionableInput(fileOrDirPath) {
+    const text = `You are an expert Angular developer assisting with a migration to zoneless.
+
+No actionable migration steps were found in the application code for \`${fileOrDirPath}\`. However, if the tests for this code are failing with zoneless enabled, the tests themselves likely need to be updated.
+
+Your task is to investigate and fix any failing tests related to the code in \`${fileOrDirPath}\`.
+
+${testDebuggingGuideText(fileOrDirPath)}
+`;
+    return createResponse(text);
+}
+async function createFixResponseForZoneTests(sourceFile) {
+    const ts = await (0, ts_utils_1.loadTypescript)();
+    const usages = [];
+    ts.forEachChild(sourceFile, function visit(node) {
+        if (ts.isCallExpression(node) &&
+            node.expression.getText(sourceFile) === 'provideZoneChangeDetection') {
+            usages.push(node);
+        }
+        ts.forEachChild(node, visit);
+    });
+    if (usages.length === 0) {
+        // No usages of provideZoneChangeDetection found, so no fix needed.
+        return null;
+    }
+    const locations = usages.map((node) => {
+        const { line, character } = sourceFile.getLineAndCharacterOfPosition(node.getStart());
+        return `line ${line + 1}, character ${character + 1}`;
+    });
+    const text = `You are an expert Angular developer assisting with a migration to zoneless. Your task is to update the test file at \`${sourceFile.fileName}\` to be fully zoneless-compatible.
+
+      The test suite has been partially migrated, but some tests were incompatible and are still using Zone.js-based change detection via \`provideZoneChangeDetection\`. You must refactor these tests to work in a zoneless environment and remove the \`provideZoneChangeDetection\` calls.
+
+      The following usages of \`provideZoneChangeDetection\` must be removed:
+      ${locations.map((loc) => `- ${loc}`).join('\n')}
+
+      After removing \`provideZoneChangeDetection\`, the tests will likely fail. Use this guide to diagnose and fix the failures.
+
+      ${testDebuggingGuideText(sourceFile.fileName)}
+
+      ### Final Step
+      After you have applied all the required changes and followed all the rules, consult this tool again for the next steps in the migration process.`;
+    return createResponse(text);
+}
+function testDebuggingGuideText(fileName) {
+    return `
+      ### Test Debugging Guide
+
+      1.  **\`ExpressionChangedAfterItHasBeenCheckedError\`**:
+        *   **Cause**: This error indicates that a value in a component's template was updated, but Angular was not notified to run change detection.
+        *   **Solution**:
+          *   If the value is in a test-only wrapper component, update the property to be a signal.
+          *   For application components, either convert the property to a signal or call \`ChangeDetectorRef.markForCheck()\` immediately after the property is updated.
+
+      2.  **Asynchronous Operations and Timing**:
+        *   **Cause**: Without Zone.js, change detection is always scheduled asynchronously. Tests that previously relied on synchronous updates might now fail. The \`fixture.whenStable()\` utility also no longer waits for timers (like \`setTimeout\` or \`setInterval\`).
+        *   **Solution**:
+          *   Avoid relying on synchronous change detection.
+          *   To wait for asynchronous operations to complete, you may need to poll for an expected state, use \`fakeAsync\` with \`tick()\`, or use a mock clock to flush timers.
+
+      3.  **Indirect Dependencies**:
+        *   **Cause**: The component itself might be zoneless-compatible, but it could be using a service or another dependency that is not.
+        *   **Solution**: Investigate the services and dependencies used by the component and its tests. Run this tool on those dependencies to identify and fix any issues.
+
+      ### IMPORTANT: Rules and Constraints
+
+      You must follow these rules without exception:
+      1.  **DO** focus only on fixing the tests for the code in \`${fileName}\`.
+      2.  **DO** remove all usages of \`provideZoneChangeDetection\` from the test file.
+      3.  **DO** apply the solutions described in the debugging guide to fix any resulting test failures.
+      4.  **DO** update properties of test components and directives to use signals. Tests often use plain objects and values and update the component state directly before calling \`fixture.detectChanges\`. This will not work and will result in \`ExpressionChangedAfterItHasBeenCheckedError\` because Angular was not notifed of the change.
+      5.  **DO NOT** make changes to application code unless it is to fix a bug revealed by the zoneless migration (e.g., converting a property to a signal to fix an \`ExpressionChangedAfterItHasBeenCheckedError\`).
+      6.  **DO NOT** make any changes unrelated to fixing the failing tests in \`${fileName}\`.
+      7.  **DO NOT** re-introduce \`provideZoneChangeDetection()\` into tests that are already using \`provideZonelessChangeDetection()\`.`;
+}
+/* eslint-enable max-len */
+function createResponse(text) {
+    return {
+        content: [{ type: 'text', text }],
+    };
+}

package/src/commands/mcp/tools/onpush-zoneless-migration/send_debug_message.d.ts

@@ -0,0 +1,10 @@
+/**
+ * @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 { RequestHandlerExtra } from '@modelcontextprotocol/sdk/shared/protocol';
+import { ServerNotification, ServerRequest } from '@modelcontextprotocol/sdk/types';
+export declare function sendDebugMessage(message: string, { sendNotification }: RequestHandlerExtra<ServerRequest, ServerNotification>): void;

package/src/commands/mcp/tools/onpush-zoneless-migration/send_debug_message.js

@@ -0,0 +1,19 @@
+"use strict";
+/**
+ * @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
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.sendDebugMessage = sendDebugMessage;
+function sendDebugMessage(message, { sendNotification }) {
+    void sendNotification({
+        method: 'notifications/message',
+        params: {
+            level: 'debug',
+            data: message,
+        },
+    });
+}