@angular/cli 21.0.0-next.2 → 21.0.0-next.4

package/lib/config/schema.json

@@ -4304,23 +4304,23 @@
       "properties": {
         "buildTarget": {
           "type": "string",
-          "description": "A build builder target to serve in the format of `project:target[:configuration]`. You can also pass in more than one configuration name as a comma-separated list. Example: `project:target:production,staging`.",
+          "description": "Specifies the build target to use for the unit test build in the format `project:target[:configuration]`. You can also pass a comma-separated list of configurations. Example: `project:target:production,staging`.",
           "pattern": "^[^:\\s]*:[^:\\s]*(:[^\\s]+)?$"
         },
         "tsConfig": {
           "type": "string",
-          "description": "The name of the TypeScript configuration file."
+          "description": "The path to the TypeScript configuration file, relative to the workspace root."
         },
         "runner": {
           "type": "string",
-          "description": "The name of the test runner to use for test execution.",
+          "description": "Specifies the test runner to use for test execution.",
           "enum": [
             "karma",
             "vitest"
           ]
         },
         "browsers": {
-          "description": "A list of browsers to use for test execution. If undefined, jsdom on Node.js will be used instead of a browser. For Vitest and Karma, browser names ending with 'Headless' (e.g., 'ChromeHeadless') will enable headless mode for that browser.",
+          "description": "Specifies the browsers to use for test execution. When not specified, tests are run in a Node.js environment using jsdom. For both Vitest and Karma, browser names ending with 'Headless' (e.g., 'ChromeHeadless') will enable headless mode.",
           "type": "array",
           "items": {
             "type": "string"
@@ -4335,41 +4335,43 @@
           "default": [
             "**/*.spec.ts"
           ],
-          "description": "Globs of files to include, relative to project root. \nThere are 2 special cases:\n - when a path to directory is provided, all spec files ending \".spec.@(ts|tsx)\" will be included\n - when a path to a file is provided, and a matching spec file exists it will be included instead."
+          "description": "Specifies glob patterns of files to include for testing, relative to the project root. This option also has special handling for directory paths (includes all `.spec.ts` files within) and file paths (includes the corresponding `.spec` file if one exists)."
         },
         "exclude": {
           "type": "array",
           "items": {
             "type": "string"
           },
-          "default": [],
-          "description": "Globs of files to exclude, relative to the project root."
+          "description": "Specifies glob patterns of files to exclude from testing, relative to the project root."
+        },
+        "filter": {
+          "type": "string",
+          "description": "Specifies a regular expression pattern to match against test suite and test names. Only tests with a name matching the pattern will be executed. For example, `^App` will run only tests in suites beginning with 'App'."
         },
         "watch": {
           "type": "boolean",
-          "description": "Re-run tests when source files change. Defaults to `true` in TTY environments and `false` otherwise."
+          "description": "Enables watch mode, which re-runs tests when source files change. Defaults to `true` in TTY environments and `false` otherwise."
         },
         "debug": {
           "type": "boolean",
-          "description": "Initialize the test runner to support using the Node Inspector for test debugging.",
+          "description": "Enables debugging mode for tests, allowing the use of the Node Inspector.",
           "default": false
         },
         "codeCoverage": {
           "type": "boolean",
-          "description": "Output a code coverage report.",
+          "description": "Enables code coverage reporting for tests.",
           "default": false
         },
         "codeCoverageExclude": {
           "type": "array",
-          "description": "Globs to exclude from code coverage.",
+          "description": "Specifies glob patterns of files to exclude from the code coverage report.",
           "items": {
             "type": "string"
-          },
-          "default": []
+          }
         },
         "codeCoverageReporters": {
           "type": "array",
-          "description": "Reporters to use for code coverage results.",
+          "description": "Specifies the reporters to use for code coverage results. Each reporter can be a string representing its name, or a tuple containing the name and an options object. Built-in reporters include 'html', 'lcov', 'lcovonly', 'text', 'text-summary', 'cobertura', 'json', and 'json-summary'.",
           "items": {
             "oneOf": [
               {
@@ -4393,14 +4395,49 @@
         },
         "reporters": {
           "type": "array",
-          "description": "Test runner reporters to use. Directly passed to the test runner.",
+          "description": "Specifies the reporters to use during test execution. Each reporter can be a string representing its name, or a tuple containing the name and an options object. Built-in reporters include 'default', 'verbose', 'dots', 'json', 'junit', 'tap', 'tap-flat', and 'html'. You can also provide a path to a custom reporter.",
           "items": {
-            "type": "string"
+            "oneOf": [
+              {
+                "anyOf": [
+                  {
+                    "$ref": "#/definitions/AngularBuildBuildersUnitTestSchema/definitions/reporters-enum"
+                  },
+                  {
+                    "type": "string"
+                  }
+                ]
+              },
+              {
+                "type": "array",
+                "minItems": 1,
+                "maxItems": 2,
+                "items": [
+                  {
+                    "anyOf": [
+                      {
+                        "$ref": "#/definitions/AngularBuildBuildersUnitTestSchema/definitions/reporters-enum"
+                      },
+                      {
+                        "type": "string"
+                      }
+                    ]
+                  },
+                  {
+                    "type": "object"
+                  }
+                ]
+              }
+            ]
           }
         },
+        "outputFile": {
+          "type": "string",
+          "description": "Specifies a file path for the test report, applying only to the first reporter. To configure output files for multiple reporters, use the tuple format `['reporter-name', { outputFile: '...' }]` within the `reporters` option. When not provided, output is written to the console."
+        },
         "providersFile": {
           "type": "string",
-          "description": "TypeScript file that exports an array of Angular providers to use during test execution. The array must be a default export.",
+          "description": "Specifies the path to a TypeScript file that provides an array of Angular providers for the test environment. The file must contain a default export of the provider array.",
           "minLength": 1
         },
         "setupFiles": {
@@ -4408,11 +4445,17 @@
           "items": {
             "type": "string"
           },
-          "description": "A list of global setup and configuration files that are included before the test files. The application's polyfills are always included before these files. The Angular Testbed is also initialized prior to the execution of these files."
+          "description": "A list of paths to global setup files that are executed before the test files. The application's polyfills and the Angular TestBed are always initialized before these files."
         },
         "progress": {
           "type": "boolean",
-          "description": "Log progress to the console while building. Defaults to the build target's progress value."
+          "description": "Shows build progress information in the console. Defaults to the `progress` setting of the specified `buildTarget`."
+        },
+        "dumpVirtualFiles": {
+          "type": "boolean",
+          "description": "Dumps build output files to the `.angular/cache` directory for debugging purposes.",
+          "default": false,
+          "visible": false
         }
       },
       "additionalProperties": false,
@@ -4428,6 +4471,19 @@
             "json",
             "json-summary"
           ]
+        },
+        "reporters-enum": {
+          "type": "string",
+          "enum": [
+            "default",
+            "verbose",
+            "dots",
+            "json",
+            "junit",
+            "tap",
+            "tap-flat",
+            "html"
+          ]
         }
       }
     },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@angular/cli",
-  "version": "21.0.0-next.2",
+  "version": "21.0.0-next.4",
   "description": "CLI tool for Angular",
   "main": "lib/cli/index.js",
   "bin": {
@@ -25,20 +25,20 @@
   },
   "homepage": "https://github.com/angular/angular-cli",
   "dependencies": {
-    "@angular-devkit/architect": "0.2100.0-next.2",
-    "@angular-devkit/core": "21.0.0-next.2",
-    "@angular-devkit/schematics": "21.0.0-next.2",
-    "@inquirer/prompts": "7.8.4",
-    "@listr2/prompt-adapter-inquirer": "3.0.3",
-    "@modelcontextprotocol/sdk": "1.17.5",
-    "@schematics/angular": "21.0.0-next.2",
+    "@angular-devkit/architect": "0.2100.0-next.4",
+    "@angular-devkit/core": "21.0.0-next.4",
+    "@angular-devkit/schematics": "21.0.0-next.4",
+    "@inquirer/prompts": "7.8.6",
+    "@listr2/prompt-adapter-inquirer": "3.0.4",
+    "@modelcontextprotocol/sdk": "1.18.0",
+    "@schematics/angular": "21.0.0-next.4",
     "@yarnpkg/lockfile": "1.1.0",
     "algoliasearch": "5.37.0",
     "ini": "5.0.0",
     "jsonc-parser": "3.3.1",
-    "listr2": "9.0.3",
+    "listr2": "9.0.4",
     "npm-package-arg": "13.0.0",
-    "pacote": "21.0.0",
+    "pacote": "21.0.1",
     "resolve": "1.22.10",
     "semver": "7.7.2",
     "yargs": "18.0.0",
@@ -47,17 +47,17 @@
   "ng-update": {
     "migrations": "@schematics/angular/migrations/migration-collection.json",
     "packageGroup": {
-      "@angular/cli": "21.0.0-next.2",
-      "@angular/build": "21.0.0-next.2",
-      "@angular/ssr": "21.0.0-next.2",
-      "@angular-devkit/architect": "0.2100.0-next.2",
-      "@angular-devkit/build-angular": "21.0.0-next.2",
-      "@angular-devkit/build-webpack": "0.2100.0-next.2",
-      "@angular-devkit/core": "21.0.0-next.2",
-      "@angular-devkit/schematics": "21.0.0-next.2"
+      "@angular/cli": "21.0.0-next.4",
+      "@angular/build": "21.0.0-next.4",
+      "@angular/ssr": "21.0.0-next.4",
+      "@angular-devkit/architect": "0.2100.0-next.4",
+      "@angular-devkit/build-angular": "21.0.0-next.4",
+      "@angular-devkit/build-webpack": "0.2100.0-next.4",
+      "@angular-devkit/core": "21.0.0-next.4",
+      "@angular-devkit/schematics": "21.0.0-next.4"
     }
   },
-  "packageManager": "pnpm@10.15.1",
+  "packageManager": "pnpm@10.17.0",
   "engines": {
     "node": "^20.19.0 || ^22.12.0 || >=24.0.0",
     "npm": "^6.11.0 || ^7.5.6 || >=8.0.0",

package/src/commands/mcp/mcp-server.d.ts

@@ -13,16 +13,6 @@ import { AnyMcpToolDeclaration } from './tools/tool-registry';
  * These tools are considered experimental and may have limitations.
  */
 export declare const EXPERIMENTAL_TOOLS: readonly [import("./tools/tool-registry").McpToolDeclaration<{
-    query: import("zod").ZodString;
-}, {
-    examples: import("zod").ZodArray<import("zod").ZodObject<{
-        content: import("zod").ZodString;
-    }, "strip", import("zod").ZodTypeAny, {
-        content: string;
-    }, {
-        content: string;
-    }>, "many">;
-}>, import("./tools/tool-registry").McpToolDeclaration<{
     transformations: import("zod").ZodOptional<import("zod").ZodArray<import("zod").ZodEnum<[string, ...string[]]>, "many">>;
 }, {
     instructions: import("zod").ZodOptional<import("zod").ZodArray<import("zod").ZodString, "many">>;

package/src/commands/mcp/mcp-server.js

@@ -28,16 +28,17 @@ const tool_registry_1 = require("./tools/tool-registry");
  * The set of tools that are enabled by default for the MCP server.
  * These tools are considered stable and suitable for general use.
  */
-const STABLE_TOOLS = [best_practices_1.BEST_PRACTICES_TOOL, doc_search_1.DOC_SEARCH_TOOL, projects_1.LIST_PROJECTS_TOOL];
+const STABLE_TOOLS = [
+    best_practices_1.BEST_PRACTICES_TOOL,
+    doc_search_1.DOC_SEARCH_TOOL,
+    examples_1.FIND_EXAMPLE_TOOL,
+    projects_1.LIST_PROJECTS_TOOL,
+];
 /**
  * The set of tools that are available but not enabled by default.
  * These tools are considered experimental and may have limitations.
  */
-exports.EXPERIMENTAL_TOOLS = [
-    examples_1.FIND_EXAMPLE_TOOL,
-    modernize_1.MODERNIZE_TOOL,
-    zoneless_migration_1.ZONELESS_MIGRATION_TOOL,
-];
+exports.EXPERIMENTAL_TOOLS = [modernize_1.MODERNIZE_TOOL, zoneless_migration_1.ZONELESS_MIGRATION_TOOL];
 async function createMcpServer(options, logger) {
     const server = new mcp_js_1.McpServer({
         name: 'angular-cli-server',
@@ -48,8 +49,34 @@ async function createMcpServer(options, logger) {
             tools: {},
             logging: {},
         },
-        instructions: 'For Angular development, this server provides tools to adhere to best practices, search documentation, and find code examples. ' +
-            'When writing or modifying Angular code, use the MCP server and its tools instead of direct shell commands where possible.',
+        instructions: `
+<General Purpose>
+This server provides a safe, programmatic interface to the Angular CLI for an AI assistant.
+Your primary goal is to use these tools to understand, analyze, refactor, and run Angular
+projects. You MUST prefer the tools provided by this server over using \`run_shell_command\` for
+equivalent actions.
+</General Purpose>
+
+<Core Workflows & Tool Guide>
+* **1. Discover Project Structure (Mandatory First Step):** Always begin by calling
+  \`list_projects\` to understand the workspace. The outputs from this tool are often
+  required inputs for other tools.
+
+* **2. Write & Modify Code:** Before writing or changing code, you MUST consult the
+  \`get_best_practices\` tool to learn the current, non-negotiable coding standards.
+
+* **3. Answer User Questions:**
+    - For conceptual questions ("what is..."), use \`search_documentation\`.
+    - For code examples ("show me how to..."), use \`find_examples\`.
+</Core Workflows & Tool Guide>
+
+<Key Concepts>
+* **Workspace vs. Project:** A 'workspace' contains an \`angular.json\` file and defines 'projects'
+  (applications or libraries). A monorepo can have multiple workspaces.
+* **Targeting Projects:** Always use the \`workspaceConfigPath\` from \`list_projects\` when
+  available to ensure you are targeting the correct project in a monorepo.
+</Key Concepts>
+`,
     });
     (0, instructions_1.registerInstructionsResource)(server);
     const toolDeclarations = assembleToolDeclarations(STABLE_TOOLS, exports.EXPERIMENTAL_TOOLS, {

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

@@ -8,13 +8,38 @@
 import { z } from 'zod';
 export declare const FIND_EXAMPLE_TOOL: import("./tool-registry").McpToolDeclaration<{
     query: z.ZodString;
+    keywords: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    required_packages: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    related_concepts: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    includeExperimental: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
 }, {
     examples: z.ZodArray<z.ZodObject<{
+        title: z.ZodString;
+        summary: z.ZodString;
+        keywords: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        required_packages: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        related_concepts: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        related_tools: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
         content: z.ZodString;
+        snippet: z.ZodOptional<z.ZodString>;
     }, "strip", z.ZodTypeAny, {
+        title: string;
         content: string;
+        summary: string;
+        keywords?: string[] | undefined;
+        required_packages?: string[] | undefined;
+        related_concepts?: string[] | undefined;
+        related_tools?: string[] | undefined;
+        snippet?: string | undefined;
     }, {
+        title: string;
         content: string;
+        summary: string;
+        keywords?: string[] | undefined;
+        required_packages?: string[] | undefined;
+        related_concepts?: string[] | undefined;
+        related_tools?: string[] | undefined;
+        snippet?: string | undefined;
     }>, "many">;
 }>;
 /**

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

@@ -50,28 +50,92 @@ const node_path_1 = __importDefault(require("node:path"));
 const zod_1 = require("zod");
 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.
-    - Example: 'standalone component' (finds results with both "standalone" and "component")
-  - OR: Use the OR operator to find results with either term.
-    - Example: 'validation OR validator'
-  - NOT: Use the NOT operator to exclude terms.
-    - Example: 'forms NOT reactive'
-  - Grouping: Use parentheses () to group expressions.
-    - Example: '(validation OR validator) AND forms'
-  - Phrase Search: Use double quotes "" for exact phrases.
-    - Example: '"template-driven forms"'
-  - Prefix Search: Use an asterisk * for prefix matching.
-    - Example: 'rout*' (matches "route", "router", "routing")
-
-Examples of queries:
-  - Find standalone components: 'standalone component'
-  - Find ngFor with trackBy: 'ngFor trackBy'
-  - Find signal inputs: 'signal input'
-  - Find lazy loading a route: 'lazy load route'
-  - Find forms with validation: 'form AND (validation OR validator)'`),
+    query: zod_1.z
+        .string()
+        .describe(`The primary, conceptual search query. This should capture the user's main goal or question ` +
+        `(e.g., 'lazy loading a route' or 'how to use signal inputs'). The query will be processed ` +
+        'by a powerful full-text search engine.\n\n' +
+        'Key Syntax Features (see https://www.sqlite.org/fts5.html for full documentation):\n' +
+        '  - AND (default): Space-separated terms are combined with AND.\n' +
+        '    - Example: \'standalone component\' (finds results with both "standalone" and "component")\n' +
+        '  - OR: Use the OR operator to find results with either term.\n' +
+        "    - Example: 'validation OR validator'\n" +
+        '  - NOT: Use the NOT operator to exclude terms.\n' +
+        "    - Example: 'forms NOT reactive'\n" +
+        '  - Grouping: Use parentheses () to group expressions.\n' +
+        "    - Example: '(validation OR validator) AND forms'\n" +
+        '  - Phrase Search: Use double quotes "" for exact phrases.\n' +
+        '    - Example: \'"template-driven forms"\'\n' +
+        '  - Prefix Search: Use an asterisk * for prefix matching.\n' +
+        '    - Example: \'rout*\' (matches "route", "router", "routing")'),
+    keywords: zod_1.z
+        .array(zod_1.z.string())
+        .optional()
+        .describe('A list of specific, exact keywords to narrow the search. Use this for precise terms like ' +
+        'API names, function names, or decorators (e.g., `ngFor`, `trackBy`, `inject`).'),
+    required_packages: zod_1.z
+        .array(zod_1.z.string())
+        .optional()
+        .describe("A list of NPM packages that an example must use. Use this when the user's request is " +
+        'specific to a feature within a certain package (e.g., if the user asks about `ngModel`, ' +
+        'you should filter by `@angular/forms`).'),
+    related_concepts: zod_1.z
+        .array(zod_1.z.string())
+        .optional()
+        .describe('A list of high-level concepts to filter by. Use this to find examples related to broader ' +
+        'architectural ideas or patterns (e.g., `signals`, `dependency injection`, `routing`).'),
+    includeExperimental: zod_1.z
+        .boolean()
+        .optional()
+        .default(false)
+        .describe('By default, this tool returns only production-safe examples. Set this to `true` **only if** ' +
+        'the user explicitly asks for a bleeding-edge feature or if a stable solution to their ' +
+        'problem cannot be found. If you set this to `true`, you **MUST** preface your answer by ' +
+        'warning the user that the example uses experimental APIs that are not suitable for production.'),
+});
+const findExampleOutputSchema = zod_1.z.object({
+    examples: zod_1.z.array(zod_1.z.object({
+        title: zod_1.z
+            .string()
+            .describe('The title of the example. Use this as a heading when presenting the example to the user.'),
+        summary: zod_1.z
+            .string()
+            .describe("A one-sentence summary of the example's purpose. Use this to help the user decide " +
+            'if the example is relevant to them.'),
+        keywords: zod_1.z
+            .array(zod_1.z.string())
+            .optional()
+            .describe('A list of keywords for the example. You can use these to explain why this example ' +
+            "was a good match for the user's query."),
+        required_packages: zod_1.z
+            .array(zod_1.z.string())
+            .optional()
+            .describe('A list of NPM packages required for the example to work. Before presenting the code, ' +
+            'you should inform the user if any of these packages need to be installed.'),
+        related_concepts: zod_1.z
+            .array(zod_1.z.string())
+            .optional()
+            .describe('A list of related concepts. You can suggest these to the user as topics for ' +
+            'follow-up questions.'),
+        related_tools: zod_1.z
+            .array(zod_1.z.string())
+            .optional()
+            .describe('A list of related MCP tools. You can suggest these as potential next steps for the user.'),
+        content: zod_1.z
+            .string()
+            .describe('A complete, self-contained Angular code example in Markdown format. This should be ' +
+            'presented to the user inside a markdown code block.'),
+        snippet: zod_1.z
+            .string()
+            .optional()
+            .describe('A contextual snippet from the content showing the matched search term. This field is ' +
+            'critical for efficiently evaluating a result`s relevance. It enables two primary ' +
+            'workflows:\n\n' +
+            '1. For direct questions: You can internally review snippets to select the single best ' +
+            'result before generating a comprehensive answer from its full `content`.\n' +
+            '2. For ambiguous or exploratory questions: You can present a summary of titles and ' +
+            'snippets to the user, allowing them to guide the next step.'),
+    })),
 });
 exports.FIND_EXAMPLE_TOOL = (0, tool_registry_1.declareTool)({
     name: 'find_examples',
@@ -89,7 +153,9 @@ new or evolving features.
 * **Modern Implementation:** Finding the correct modern syntax for features
   (e.g., query: 'functional route guard' or 'http client with fetch').
 * **Refactoring to Modern Patterns:** Upgrading older code by finding examples of new syntax
-  (e.g., query: 'built-in control flow' to replace "*ngIf').
+  (e.g., query: 'built-in control flow' to replace "*ngIf").
+* **Advanced Filtering:** Combining a full-text search with filters to narrow results.
+  (e.g., query: 'forms', required_packages: ['@angular/forms'], keywords: ['validation'])
 </Use Cases>
 <Operational Notes>
 * **Tool Selection:** This database primarily contains examples for new and recently updated Angular
@@ -98,15 +164,11 @@ new or evolving features.
 * The examples in this database are the single source of truth for modern Angular coding patterns.
 * The search query uses a powerful full-text search syntax (FTS5). Refer to the 'query'
   parameter description for detailed syntax rules and examples.
+* You can combine the main 'query' with optional filters like 'keywords', 'required_packages',
+  and 'related_concepts' to create highly specific searches.
 </Operational Notes>`,
     inputSchema: findExampleInputSchema.shape,
-    outputSchema: {
-        examples: zod_1.z.array(zod_1.z.object({
-            content: zod_1.z
-                .string()
-                .describe('A complete, self-contained Angular code example in Markdown format.'),
-        })),
-    },
+    outputSchema: findExampleOutputSchema.shape,
     isReadOnly: true,
     isLocalOnly: true,
     shouldRegister: ({ logger }) => {
@@ -123,12 +185,11 @@ new or evolving features.
 });
 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 }) => {
+    return async (input) => {
         if (!db) {
             if (!exampleDatabasePath) {
                 // This should be prevented by the registration logic in mcp-server.ts
@@ -137,17 +198,67 @@ async function createFindExampleHandler({ exampleDatabasePath }) {
             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 { query, keywords, required_packages, related_concepts, includeExperimental } = input;
+        // Build the query dynamically
+        const params = [];
+        let sql = 'SELECT title, summary, keywords, required_packages, related_concepts, related_tools, content, ' +
+            // The `snippet` function generates a contextual snippet of the matched text.
+            // Column 6 is the `content` column. We highlight matches with asterisks and limit the snippet size.
+            "snippet(examples_fts, 6, '**', '**', '...', 15) AS snippet " +
+            'FROM examples_fts';
+        const whereClauses = [];
+        // FTS query
+        if (query) {
+            whereClauses.push('examples_fts MATCH ?');
+            params.push(escapeSearchQuery(query));
+        }
+        // JSON array filters
+        const addJsonFilter = (column, values) => {
+            if (values?.length) {
+                for (const value of values) {
+                    whereClauses.push(`${column} LIKE ?`);
+                    params.push(`%"${value}"%`);
+                }
+            }
+        };
+        addJsonFilter('keywords', keywords);
+        addJsonFilter('required_packages', required_packages);
+        addJsonFilter('related_concepts', related_concepts);
+        if (!includeExperimental) {
+            whereClauses.push('experimental = 0');
+        }
+        if (whereClauses.length > 0) {
+            sql += ` WHERE ${whereClauses.join(' AND ')}`;
         }
-        const sanitizedQuery = escapeSearchQuery(query);
+        // Order the results by relevance using the BM25 algorithm.
+        // The weights assigned to each column boost the ranking of documents where the
+        // search term appears in a more important field.
+        // Column order: title, summary, keywords, required_packages, related_concepts, related_tools, content
+        sql += ' ORDER BY bm25(examples_fts, 10.0, 5.0, 5.0, 1.0, 2.0, 1.0, 1.0);';
+        const queryStatement = db.prepare(sql);
         // Query database and return results
         const examples = [];
         const textContent = [];
-        for (const exampleRecord of queryStatement.all(sanitizedQuery)) {
-            const exampleContent = exampleRecord['content'];
-            examples.push({ content: exampleContent });
-            textContent.push({ type: 'text', text: exampleContent });
+        for (const exampleRecord of queryStatement.all(...params)) {
+            const record = exampleRecord;
+            const example = {
+                title: record['title'],
+                summary: record['summary'],
+                keywords: JSON.parse(record['keywords'] || '[]'),
+                required_packages: JSON.parse(record['required_packages'] || '[]'),
+                related_concepts: JSON.parse(record['related_concepts'] || '[]'),
+                related_tools: JSON.parse(record['related_tools'] || '[]'),
+                content: record['content'],
+                snippet: record['snippet'],
+            };
+            examples.push(example);
+            // Also create a more structured text output
+            let text = `## Example: ${example.title}\n**Summary:** ${example.summary}`;
+            if (example.snippet) {
+                text += `\n**Snippet:** ${example.snippet}`;
+            }
+            text += `\n\n---\n\n${example.content}`;
+            textContent.push({ type: 'text', text });
         }
         return {
             content: textContent,
@@ -232,18 +343,131 @@ function suppressSqliteWarning() {
         return originalProcessEmit.apply(process, arguments);
     };
 }
+/**
+ * A simple YAML front matter parser.
+ *
+ * This function extracts the YAML block enclosed by `---` at the beginning of a string
+ * and parses it into a JavaScript object. It is not a full YAML parser and only
+ * supports simple key-value pairs and string arrays.
+ *
+ * @param content The string content to parse.
+ * @returns A record containing the parsed front matter data.
+ */
+function parseFrontmatter(content) {
+    const match = content.match(/^---\r?\n(.*?)\r?\n---/s);
+    if (!match) {
+        return {};
+    }
+    const frontmatter = match[1];
+    const data = {};
+    const lines = frontmatter.split(/\r?\n/);
+    let currentKey = '';
+    let isArray = false;
+    const arrayValues = [];
+    for (const line of lines) {
+        const keyValueMatch = line.match(/^([^:]+):\s*(.*)/);
+        if (keyValueMatch) {
+            if (currentKey && isArray) {
+                data[currentKey] = arrayValues.slice();
+                arrayValues.length = 0;
+            }
+            const [, key, value] = keyValueMatch;
+            currentKey = key.trim();
+            isArray = value.trim() === '';
+            if (!isArray) {
+                const trimmedValue = value.trim();
+                if (trimmedValue === 'true') {
+                    data[currentKey] = true;
+                }
+                else if (trimmedValue === 'false') {
+                    data[currentKey] = false;
+                }
+                else {
+                    data[currentKey] = trimmedValue;
+                }
+            }
+        }
+        else {
+            const arrayItemMatch = line.match(/^\s*-\s*(.*)/);
+            if (arrayItemMatch && currentKey && isArray) {
+                arrayValues.push(arrayItemMatch[1].trim());
+            }
+        }
+    }
+    if (currentKey && isArray) {
+        data[currentKey] = arrayValues;
+    }
+    return data;
+}
 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(?);');
+    // Create a relational table to store the structured example data.
+    db.exec(`
+    CREATE TABLE examples (
+      id INTEGER PRIMARY KEY,
+      title TEXT NOT NULL,
+      summary TEXT NOT NULL,
+      keywords TEXT,
+      required_packages TEXT,
+      related_concepts TEXT,
+      related_tools TEXT,
+      experimental INTEGER NOT NULL DEFAULT 0,
+      content TEXT NOT NULL
+    );
+  `);
+    // Create an FTS5 virtual table to provide full-text search capabilities.
+    db.exec(`
+    CREATE VIRTUAL TABLE examples_fts USING fts5(
+      title,
+      summary,
+      keywords,
+      required_packages,
+      related_concepts,
+      related_tools,
+      content,
+      content='examples',
+      content_rowid='id',
+      tokenize = 'porter ascii'
+    );
+  `);
+    // Create triggers to keep the FTS table synchronized with the examples table.
+    db.exec(`
+    CREATE TRIGGER examples_after_insert AFTER INSERT ON examples BEGIN
+      INSERT INTO examples_fts(rowid, title, summary, keywords, required_packages, related_concepts, related_tools, content)
+      VALUES (
+        new.id, new.title, new.summary, new.keywords, new.required_packages, new.related_concepts,
+        new.related_tools, new.content
+      );
+    END;
+  `);
+    const insertStatement = db.prepare('INSERT INTO examples(' +
+        'title, summary, keywords, required_packages, related_concepts, related_tools, experimental, content' +
+        ') VALUES(?, ?, ?, ?, ?, ?, ?, ?);');
+    const frontmatterSchema = zod_1.z.object({
+        title: zod_1.z.string(),
+        summary: zod_1.z.string(),
+        keywords: zod_1.z.array(zod_1.z.string()).optional(),
+        required_packages: zod_1.z.array(zod_1.z.string()).optional(),
+        related_concepts: zod_1.z.array(zod_1.z.string()).optional(),
+        related_tools: zod_1.z.array(zod_1.z.string()).optional(),
+        experimental: zod_1.z.boolean().optional(),
+    });
     db.exec('BEGIN TRANSACTION');
-    for await (const entry of (0, promises_1.glob)('*.md', { cwd: examplesPath, withFileTypes: true })) {
+    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);
+        const content = await (0, promises_1.readFile)(node_path_1.default.join(entry.parentPath, entry.name), 'utf-8');
+        const frontmatter = parseFrontmatter(content);
+        const validation = frontmatterSchema.safeParse(frontmatter);
+        if (!validation.success) {
+            // eslint-disable-next-line no-console
+            console.warn(`Skipping invalid example file ${entry.name}:`, validation.error.issues);
+            continue;
+        }
+        const { title, summary, keywords, required_packages, related_concepts, related_tools, experimental, } = validation.data;
+        insertStatement.run(title, summary, JSON.stringify(keywords ?? []), JSON.stringify(required_packages ?? []), JSON.stringify(related_concepts ?? []), JSON.stringify(related_tools ?? []), experimental ? 1 : 0, content);
     }
     db.exec('END TRANSACTION');
     return db;

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

@@ -148,6 +148,7 @@ function generateZonelessMigrationInstructionsForComponent(filePath) {
   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.
+  6.  **DO NOT** remove or modify usages of \`NgZone.run\` or \`NgZone.runOutsideAngular\`. These are still required.
 
   ### 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.`;

package/src/utilities/package-manager.d.ts

@@ -12,8 +12,14 @@ export interface PackageManagerUtilsContext {
     workspace?: AngularWorkspace;
     root: string;
 }
+/**
+ * Utilities for interacting with various package managers.
+ */
 export declare class PackageManagerUtils {
     private readonly context;
+    /**
+     * @param context The context for the package manager utilities, including workspace and global configuration.
+     */
     constructor(context: PackageManagerUtilsContext);
     /** Get the package manager name. */
     get name(): PackageManager;
@@ -32,6 +38,12 @@ export declare class PackageManagerUtils {
     private run;
     private getVersion;
     private getName;
+    /**
+     * Checks if a lockfile for a specific package manager exists in the root directory.
+     * @param packageManager The package manager to check for.
+     * @param filesInRoot An array of file names in the root directory.
+     * @returns True if the lockfile exists, false otherwise.
+     */
     private hasLockfile;
     private getConfiguredPackageManager;
 }

package/src/utilities/package-manager.js

@@ -50,6 +50,18 @@ const node_path_1 = require("node:path");
 const workspace_schema_1 = require("../../lib/config/workspace-schema");
 const config_1 = require("./config");
 const memoize_1 = require("./memoize");
+/**
+ * A map of package managers to their corresponding lockfile names.
+ */
+const LOCKFILE_NAMES = {
+    [workspace_schema_1.PackageManager.Yarn]: 'yarn.lock',
+    [workspace_schema_1.PackageManager.Pnpm]: 'pnpm-lock.yaml',
+    [workspace_schema_1.PackageManager.Bun]: ['bun.lockb', 'bun.lock'],
+    [workspace_schema_1.PackageManager.Npm]: 'package-lock.json',
+};
+/**
+ * Utilities for interacting with various package managers.
+ */
 let PackageManagerUtils = (() => {
     let _instanceExtraInitializers = [];
     let _getVersion_decorators;
@@ -64,6 +76,9 @@ let PackageManagerUtils = (() => {
             if (_metadata) Object.defineProperty(this, Symbol.metadata, { enumerable: true, configurable: true, writable: true, value: _metadata });
         }
         context = __runInitializers(this, _instanceExtraInitializers);
+        /**
+         * @param context The context for the package manager utilities, including workspace and global configuration.
+         */
         constructor(context) {
             this.context = context;
         }
@@ -211,10 +226,11 @@ let PackageManagerUtils = (() => {
             if (packageManager) {
                 return packageManager;
             }
-            const hasNpmLock = this.hasLockfile(workspace_schema_1.PackageManager.Npm);
-            const hasYarnLock = this.hasLockfile(workspace_schema_1.PackageManager.Yarn);
-            const hasPnpmLock = this.hasLockfile(workspace_schema_1.PackageManager.Pnpm);
-            const hasBunLock = this.hasLockfile(workspace_schema_1.PackageManager.Bun);
+            const filesInRoot = (0, node_fs_1.readdirSync)(this.context.root);
+            const hasNpmLock = this.hasLockfile(workspace_schema_1.PackageManager.Npm, filesInRoot);
+            const hasYarnLock = this.hasLockfile(workspace_schema_1.PackageManager.Yarn, filesInRoot);
+            const hasPnpmLock = this.hasLockfile(workspace_schema_1.PackageManager.Pnpm, filesInRoot);
+            const hasBunLock = this.hasLockfile(workspace_schema_1.PackageManager.Bun, filesInRoot);
             // PERF NOTE: `this.getVersion` spawns the package a the child_process which can take around ~300ms at times.
             // Therefore, we should only call this method when needed. IE: don't call `this.getVersion(PackageManager.Pnpm)` unless truly needed.
             // The result of this method is not stored in a variable because it's memoized.
@@ -259,24 +275,17 @@ let PackageManagerUtils = (() => {
             //       Potentially with a prompt to choose and optionally set as the default.
             return workspace_schema_1.PackageManager.Npm;
         }
-        hasLockfile(packageManager) {
-            let lockfileName;
-            switch (packageManager) {
-                case workspace_schema_1.PackageManager.Yarn:
-                    lockfileName = 'yarn.lock';
-                    break;
-                case workspace_schema_1.PackageManager.Pnpm:
-                    lockfileName = 'pnpm-lock.yaml';
-                    break;
-                case workspace_schema_1.PackageManager.Bun:
-                    lockfileName = 'bun.lockb';
-                    break;
-                case workspace_schema_1.PackageManager.Npm:
-                default:
-                    lockfileName = 'package-lock.json';
-                    break;
-            }
-            return (0, node_fs_1.existsSync)((0, node_path_1.join)(this.context.root, lockfileName));
+        /**
+         * Checks if a lockfile for a specific package manager exists in the root directory.
+         * @param packageManager The package manager to check for.
+         * @param filesInRoot An array of file names in the root directory.
+         * @returns True if the lockfile exists, false otherwise.
+         */
+        hasLockfile(packageManager, filesInRoot) {
+            const lockfiles = LOCKFILE_NAMES[packageManager];
+            return typeof lockfiles === 'string'
+                ? filesInRoot.includes(lockfiles)
+                : lockfiles.some((lockfile) => filesInRoot.includes(lockfile));
         }
         getConfiguredPackageManager() {
             const getPackageManager = (source) => {

package/src/utilities/version.js

@@ -22,4 +22,4 @@ class Version {
         this.patch = patch;
     }
 }
-exports.VERSION = new Version('21.0.0-next.2');
+exports.VERSION = new Version('21.0.0-next.4');