@angular/cli 20.2.0-next.2 → 20.2.0-rc.0

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

@@ -39,34 +39,18 @@ var __importStar = (this && this.__importStar) || (function () {
         return result;
     };
 })();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.registerFindExampleTool = registerFindExampleTool;
+exports.FIND_EXAMPLE_TOOL = void 0;
 exports.escapeSearchQuery = escapeSearchQuery;
+const promises_1 = require("node:fs/promises");
+const node_path_1 = __importDefault(require("node:path"));
 const zod_1 = require("zod");
-/**
- * Registers the `find_examples` tool with the MCP server.
- *
- * This tool allows users to search for best-practice Angular code examples
- * from a local SQLite database.
- *
- * @param server The MCP server instance.
- * @param exampleDatabasePath The path to the SQLite database file containing the examples.
- */
-function registerFindExampleTool(server, exampleDatabasePath) {
-    let db;
-    let queryStatement;
-    server.registerTool('find_examples', {
-        title: 'Find Angular Code Examples',
-        description: 'Before writing or modifying any Angular code including templates, ' +
-            '**ALWAYS** use this tool to find current best-practice examples. ' +
-            'This is critical for ensuring code quality and adherence to modern Angular standards. ' +
-            'This tool searches a curated database of approved Angular code examples and returns the most relevant results for your query. ' +
-            'Example Use Cases: ' +
-            "1) Creating new components, directives, or services (e.g., query: 'standalone component' or 'signal input'). " +
-            "2) Implementing core features (e.g., query: 'lazy load route', 'httpinterceptor', or 'route guard'). " +
-            "3) Refactoring existing code to use modern patterns (e.g., query: 'ngfor trackby' or 'form validation').",
-        inputSchema: {
-            query: zod_1.z.string().describe(`Performs a full-text search using FTS5 syntax. The query should target relevant Angular concepts.
+const tool_registry_1 = require("./tool-registry");
+const findExampleInputSchema = zod_1.z.object({
+    query: zod_1.z.string().describe(`Performs a full-text search using FTS5 syntax. The query should target relevant Angular concepts.
 
 Key Syntax Features (see https://www.sqlite.org/fts5.html for full documentation):
   - AND (default): Space-separated terms are combined with AND.
@@ -88,16 +72,50 @@ Examples of queries:
   - Find signal inputs: 'signal input'
   - Find lazy loading a route: 'lazy load route'
   - Find forms with validation: 'form AND (validation OR validator)'`),
-        },
-        annotations: {
-            readOnlyHint: true,
-            openWorldHint: false,
-        },
-    }, async ({ query }) => {
-        if (!db || !queryStatement) {
-            suppressSqliteWarning();
+});
+exports.FIND_EXAMPLE_TOOL = (0, tool_registry_1.declareTool)({
+    name: 'find_examples',
+    title: 'Find Angular Code Examples',
+    description: 'Before writing or modifying any Angular code including templates, ' +
+        '**ALWAYS** use this tool to find current best-practice examples. ' +
+        'This is critical for ensuring code quality and adherence to modern Angular standards. ' +
+        'This tool searches a curated database of approved Angular code examples and returns the most relevant results for your query. ' +
+        'Example Use Cases: ' +
+        "1) Creating new components, directives, or services (e.g., query: 'standalone component' or 'signal input'). " +
+        "2) Implementing core features (e.g., query: 'lazy load route', 'httpinterceptor', or 'route guard'). " +
+        "3) Refactoring existing code to use modern patterns (e.g., query: 'ngfor trackby' or 'form validation').",
+    inputSchema: findExampleInputSchema.shape,
+    isReadOnly: true,
+    isLocalOnly: true,
+    shouldRegister: ({ logger }) => {
+        // sqlite database support requires Node.js 22.16+
+        const [nodeMajor, nodeMinor] = process.versions.node.split('.', 2).map(Number);
+        if (nodeMajor < 22 || (nodeMajor === 22 && nodeMinor < 16)) {
+            logger.warn(`MCP tool 'find_examples' requires Node.js 22.16 (or higher). ` +
+                ' Registration of this tool has been skipped.');
+            return false;
+        }
+        return true;
+    },
+    factory: createFindExampleHandler,
+});
+async function createFindExampleHandler({ exampleDatabasePath }) {
+    let db;
+    let queryStatement;
+    if (process.env['NG_MCP_EXAMPLES_DIR']) {
+        db = await setupRuntimeExamples(process.env['NG_MCP_EXAMPLES_DIR']);
+    }
+    suppressSqliteWarning();
+    return async ({ query }) => {
+        if (!db) {
+            if (!exampleDatabasePath) {
+                // This should be prevented by the registration logic in mcp-server.ts
+                throw new Error('Example database path is not available.');
+            }
             const { DatabaseSync } = await Promise.resolve().then(() => __importStar(require('node:sqlite')));
             db = new DatabaseSync(exampleDatabasePath, { readOnly: true });
+        }
+        if (!queryStatement) {
             queryStatement = db.prepare('SELECT * from examples WHERE examples MATCH ? ORDER BY rank;');
         }
         const sanitizedQuery = escapeSearchQuery(query);
@@ -109,7 +127,7 @@ Examples of queries:
         return {
             content,
         };
-    });
+    };
 }
 /**
  * Escapes a search query for FTS5 by tokenizing and quoting terms.
@@ -188,3 +206,19 @@ function suppressSqliteWarning() {
         return originalProcessEmit.apply(process, arguments);
     };
 }
+async function setupRuntimeExamples(examplesPath) {
+    const { DatabaseSync } = await Promise.resolve().then(() => __importStar(require('node:sqlite')));
+    const db = new DatabaseSync(':memory:');
+    db.exec(`CREATE VIRTUAL TABLE examples USING fts5(content, tokenize = 'porter ascii');`);
+    const insertStatement = db.prepare('INSERT INTO examples(content) VALUES(?);');
+    db.exec('BEGIN TRANSACTION');
+    for await (const entry of (0, promises_1.glob)('*.md', { cwd: examplesPath, withFileTypes: true })) {
+        if (!entry.isFile()) {
+            continue;
+        }
+        const example = await (0, promises_1.readFile)(node_path_1.default.join(entry.parentPath, entry.name), 'utf-8');
+        insertStatement.run(example);
+    }
+    db.exec('END TRANSACTION');
+    return db;
+}

package/src/commands/mcp/tools/modernize.d.ts

@@ -0,0 +1,31 @@
+/**
+ * @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 { z } from 'zod';
+declare const modernizeInputSchema: z.ZodObject<{
+    transformations: z.ZodOptional<z.ZodArray<z.ZodEnum<[string, ...string[]]>, "many">>;
+}, "strip", z.ZodTypeAny, {
+    transformations?: string[] | undefined;
+}, {
+    transformations?: string[] | undefined;
+}>;
+export type ModernizeInput = z.infer<typeof modernizeInputSchema>;
+export declare function runModernization(input: ModernizeInput): Promise<{
+    content: {
+        type: "text";
+        text: string;
+    }[];
+    structuredContent: {
+        instructions: string[];
+    };
+}>;
+export declare const MODERNIZE_TOOL: import("./tool-registry").McpToolDeclaration<{
+    transformations: z.ZodOptional<z.ZodArray<z.ZodEnum<[string, ...string[]]>, "many">>;
+}, {
+    instructions: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+}>;
+export {};

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

@@ -0,0 +1,135 @@
+"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.MODERNIZE_TOOL = void 0;
+exports.runModernization = runModernization;
+const zod_1 = require("zod");
+const tool_registry_1 = require("./tool-registry");
+const TRANSFORMATIONS = [
+    {
+        name: 'control-flow-migration',
+        description: 'Migrates from `*ngIf`, `*ngFor`, and `*ngSwitch` to the new `@if`, `@for`, and `@switch` block syntax in templates.',
+        documentationUrl: 'https://angular.dev/reference/migrations/control-flow',
+    },
+    {
+        name: 'self-closing-tags-migration',
+        description: 'Converts tags for elements with no content to be self-closing (e.g., `<app-foo></app-foo>` becomes `<app-foo />`).',
+        documentationUrl: 'https://angular.dev/reference/migrations/self-closing-tags',
+    },
+    {
+        name: 'test-bed-get',
+        description: 'Updates `TestBed.get` to the preferred and type-safe `TestBed.inject` in TypeScript test files.',
+        documentationUrl: 'https://angular.dev/guide/testing/dependency-injection',
+    },
+    {
+        name: 'inject',
+        description: 'Converts usages of constructor-based injection to the inject() function.',
+        documentationUrl: 'https://angular.dev/reference/migrations/inject-function',
+    },
+    {
+        name: 'output-migration',
+        description: 'Converts `@Output` declarations to the new functional `output()` syntax.',
+        documentationUrl: 'https://angular.dev/reference/migrations/outputs',
+    },
+    {
+        name: 'signal-input-migration',
+        description: 'Migrates `@Input` declarations to the new signal-based `input()` syntax.',
+        documentationUrl: 'https://angular.dev/reference/migrations/signal-inputs',
+    },
+    {
+        name: 'signal-queries-migration',
+        description: 'Migrates `@ViewChild` and `@ContentChild` queries to their signal-based `viewChild` and `contentChild` versions.',
+        documentationUrl: 'https://angular.dev/reference/migrations/signal-queries',
+    },
+    {
+        name: 'standalone',
+        description: 'Converts the application to use standalone components, directives, and pipes. This is a ' +
+            'three-step process. After each step, you should verify that your application builds and ' +
+            'runs correctly.',
+        instructions: 'This migration requires running a cli schematic multiple times. Run the commands in the ' +
+            'order listed below, verifying that your code builds and runs between each step:\n\n' +
+            '1. Run `ng g @angular/core:standalone` and select "Convert all components, directives and pipes to standalone"\n' +
+            '2. Run `ng g @angular/core:standalone` and select "Remove unnecessary NgModule classes"\n' +
+            '3. Run `ng g @angular/core:standalone` and select "Bootstrap the project using standalone APIs"',
+        documentationUrl: 'https://angular.dev/reference/migrations/standalone',
+    },
+    {
+        name: 'zoneless',
+        description: 'Migrates the application to be zoneless.',
+        documentationUrl: 'https://angular.dev/guide/zoneless',
+    },
+];
+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(),
+});
+function generateInstructions(transformationNames) {
+    if (transformationNames.length === 0) {
+        return [
+            'See https://angular.dev/best-practices for Angular best practices. ' +
+                'You can call this tool if you have specific transformation you want to run.',
+        ];
+    }
+    const instructions = [];
+    const transformationsToRun = TRANSFORMATIONS.filter((t) => transformationNames?.includes(t.name));
+    for (const transformation of transformationsToRun) {
+        let transformationInstructions = '';
+        if (transformation.instructions) {
+            transformationInstructions = transformation.instructions;
+        }
+        else {
+            // If no instructions are included, default to running a cli schematic with the transformation name.
+            const command = `ng generate @angular/core:${transformation.name}`;
+            transformationInstructions = `To run the ${transformation.name} migration, execute the following command: \`${command}\`.`;
+        }
+        if (transformation.documentationUrl) {
+            transformationInstructions += `\nFor more information, see ${transformation.documentationUrl}.`;
+        }
+        instructions.push(transformationInstructions);
+    }
+    return instructions;
+}
+async function runModernization(input) {
+    const structuredContent = { instructions: generateInstructions(input.transformations ?? []) };
+    return {
+        content: [{ type: 'text', text: JSON.stringify(structuredContent) }],
+        structuredContent,
+    };
+}
+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',
+    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.'),
+    },
+    isLocalOnly: true,
+    isReadOnly: true,
+    factory: () => (input) => runModernization(input),
+});

package/src/commands/mcp/tools/projects.d.ts

@@ -5,8 +5,25 @@
  * 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 { McpServer } from '@modelcontextprotocol/sdk/server/mcp';
-import type { AngularWorkspace } from '../../../utilities/config';
-export declare function registerListProjectsTool(server: McpServer, context: {
-    workspace?: AngularWorkspace;
-}): void;
+import z from 'zod';
+export declare const LIST_PROJECTS_TOOL: import("./tool-registry").McpToolDeclaration<z.ZodRawShape, {
+    projects: z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        type: z.ZodOptional<z.ZodEnum<["application", "library"]>>;
+        root: z.ZodString;
+        sourceRoot: z.ZodString;
+        selectorPrefix: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        name: string;
+        root: string;
+        sourceRoot: string;
+        type?: "application" | "library" | undefined;
+        selectorPrefix?: string | undefined;
+    }, {
+        name: string;
+        root: string;
+        sourceRoot: string;
+        type?: "application" | "library" | undefined;
+        selectorPrefix?: string | undefined;
+    }>, "many">;
+}>;

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

@@ -10,42 +10,44 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.registerListProjectsTool = registerListProjectsTool;
+exports.LIST_PROJECTS_TOOL = void 0;
 const node_path_1 = __importDefault(require("node:path"));
 const zod_1 = __importDefault(require("zod"));
-function registerListProjectsTool(server, context) {
-    server.registerTool('list_projects', {
-        title: 'List Angular Projects',
-        description: 'Lists the names of all applications and libraries defined within an Angular workspace. ' +
-            'It reads the `angular.json` configuration file to identify the projects. ',
-        annotations: {
-            readOnlyHint: true,
-            openWorldHint: false,
-        },
-        outputSchema: {
-            projects: zod_1.default.array(zod_1.default.object({
-                name: zod_1.default
-                    .string()
-                    .describe('The name of the project, as defined in the `angular.json` file.'),
-                type: zod_1.default
-                    .enum(['application', 'library'])
-                    .optional()
-                    .describe(`The type of the project, either 'application' or 'library'.`),
-                root: zod_1.default
-                    .string()
-                    .describe('The root directory of the project, relative to the workspace root.'),
-                sourceRoot: zod_1.default
-                    .string()
-                    .describe(`The root directory of the project's source files, relative to the workspace root.`),
-                selectorPrefix: zod_1.default
-                    .string()
-                    .optional()
-                    .describe('The prefix to use for component selectors.' +
-                    ` For example, a prefix of 'app' would result in selectors like '<app-my-component>'.`),
-            })),
-        },
-    }, async () => {
-        const { workspace } = context;
+const tool_registry_1 = require("./tool-registry");
+exports.LIST_PROJECTS_TOOL = (0, tool_registry_1.declareTool)({
+    name: 'list_projects',
+    title: 'List Angular Projects',
+    description: 'Lists the names of all applications and libraries defined within an Angular workspace. ' +
+        'It reads the `angular.json` configuration file to identify the projects. ',
+    outputSchema: {
+        projects: zod_1.default.array(zod_1.default.object({
+            name: zod_1.default
+                .string()
+                .describe('The name of the project, as defined in the `angular.json` file.'),
+            type: zod_1.default
+                .enum(['application', 'library'])
+                .optional()
+                .describe(`The type of the project, either 'application' or 'library'.`),
+            root: zod_1.default
+                .string()
+                .describe('The root directory of the project, relative to the workspace root.'),
+            sourceRoot: zod_1.default
+                .string()
+                .describe(`The root directory of the project's source files, relative to the workspace root.`),
+            selectorPrefix: zod_1.default
+                .string()
+                .optional()
+                .describe('The prefix to use for component selectors.' +
+                ` For example, a prefix of 'app' would result in selectors like '<app-my-component>'.`),
+        })),
+    },
+    isReadOnly: true,
+    isLocalOnly: true,
+    shouldRegister: (context) => !!context.workspace,
+    factory: createListProjectsHandler,
+});
+function createListProjectsHandler({ workspace }) {
+    return async () => {
         if (!workspace) {
             return {
                 content: [
@@ -81,5 +83,5 @@ function registerListProjectsTool(server, context) {
             ],
             structuredContent: { projects },
         };
-    });
+    };
 }

package/src/commands/mcp/tools/tool-registry.d.ts

@@ -0,0 +1,35 @@
+/**
+ * @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 { McpServer, ToolCallback } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { ZodRawShape } from 'zod';
+import type { AngularWorkspace } from '../../../utilities/config';
+type ToolConfig = Parameters<McpServer['registerTool']>[1];
+export interface McpToolContext {
+    workspace?: AngularWorkspace;
+    logger: {
+        warn(text: string): void;
+    };
+    exampleDatabasePath?: string;
+}
+export type McpToolFactory<TInput extends ZodRawShape> = (context: McpToolContext) => ToolCallback<TInput> | Promise<ToolCallback<TInput>>;
+export interface McpToolDeclaration<TInput extends ZodRawShape, TOutput extends ZodRawShape> {
+    name: string;
+    title?: string;
+    description: string;
+    annotations?: ToolConfig['annotations'];
+    inputSchema?: TInput;
+    outputSchema?: TOutput;
+    factory: McpToolFactory<TInput>;
+    shouldRegister?: (context: McpToolContext) => boolean | Promise<boolean>;
+    isReadOnly?: boolean;
+    isLocalOnly?: boolean;
+}
+export type AnyMcpToolDeclaration = McpToolDeclaration<any, any>;
+export declare function declareTool<TInput extends ZodRawShape, TOutput extends ZodRawShape>(declaration: McpToolDeclaration<TInput, TOutput>): McpToolDeclaration<TInput, TOutput>;
+export declare function registerTools(server: McpServer, context: McpToolContext, declarations: AnyMcpToolDeclaration[]): Promise<void>;
+export {};

package/src/commands/mcp/tools/tool-registry.js

@@ -0,0 +1,33 @@
+"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.declareTool = declareTool;
+exports.registerTools = registerTools;
+function declareTool(declaration) {
+    return declaration;
+}
+async function registerTools(server, context, declarations) {
+    for (const declaration of declarations) {
+        if (declaration.shouldRegister && !(await declaration.shouldRegister(context))) {
+            continue;
+        }
+        const { name, factory, shouldRegister, isReadOnly, isLocalOnly, ...config } = declaration;
+        const handler = await factory(context);
+        // Add declarative characteristics to annotations
+        config.annotations ??= {};
+        if (isReadOnly !== undefined) {
+            config.annotations.readOnlyHint = isReadOnly;
+        }
+        if (isLocalOnly !== undefined) {
+            // openWorldHint: false means local only
+            config.annotations.openWorldHint = !isLocalOnly;
+        }
+        server.registerTool(name, config, handler);
+    }
+}

package/src/commands/version/cli.d.ts

@@ -5,14 +5,36 @@
  * 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 { Argv } from 'yargs';
+import type { Argv } from 'yargs';
 import { CommandModule, CommandModuleImplementation } from '../../command-builder/command-module';
+/**
+ * The command-line module for the `ng version` command.
+ */
 export default class VersionCommandModule extends CommandModule implements CommandModuleImplementation {
     command: string;
     aliases: string[] | undefined;
     describe: string;
     longDescriptionPath?: string | undefined;
+    /**
+     * Builds the command-line options for the `ng version` command.
+     * @param localYargs The `yargs` instance to configure.
+     * @returns The configured `yargs` instance.
+     */
     builder(localYargs: Argv): Argv;
+    /**
+     * The main execution logic for the `ng version` command.
+     */
     run(): Promise<void>;
-    private getVersion;
+    /**
+     * Formats the Angular packages section of the version output.
+     * @param versionInfo An object containing the version information.
+     * @returns A string containing the formatted Angular packages information.
+     */
+    private formatAngularPackages;
+    /**
+     * Formats the package table section of the version output.
+     * @param versions A map of package names to their versions.
+     * @returns A string containing the formatted package table.
+     */
+    private formatPackageTable;
 }