@angular/cli 22.0.0-rc.0 → 22.0.0-rc.2

package/bin/ng.js

@@ -57,7 +57,7 @@ if (major === 23 || major === 25) {
 
   require('./bootstrap');
 } else if (!nodeUtils.isNodeVersionSupported()) {
-  // Error and exit if less than 22.22 or 24.13.1
+  // Error and exit if less than the supported versions.
   console.error(
     'Node.js version ' +
       process.version +

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@angular/cli",
-  "version": "22.0.0-rc.0",
+  "version": "22.0.0-rc.2",
   "description": "CLI tool for Angular",
   "main": "lib/cli/index.js",
   "bin": {
@@ -15,13 +15,13 @@
     "sdk"
   ],
   "dependencies": {
-    "@angular-devkit/architect": "0.2200.0-rc.0",
-    "@angular-devkit/core": "22.0.0-rc.0",
-    "@angular-devkit/schematics": "22.0.0-rc.0",
+    "@angular-devkit/architect": "0.2200.0-rc.2",
+    "@angular-devkit/core": "22.0.0-rc.2",
+    "@angular-devkit/schematics": "22.0.0-rc.2",
     "@inquirer/prompts": "8.4.2",
     "@listr2/prompt-adapter-inquirer": "4.2.3",
     "@modelcontextprotocol/sdk": "1.29.0",
-    "@schematics/angular": "22.0.0-rc.0",
+    "@schematics/angular": "22.0.0-rc.2",
     "@yarnpkg/lockfile": "1.1.0",
     "algoliasearch": "5.52.0",
     "ini": "6.0.0",
@@ -37,14 +37,14 @@
   "ng-update": {
     "migrations": "@schematics/angular/migrations/migration-collection.json",
     "packageGroup": {
-      "@angular/cli": "22.0.0-rc.0",
-      "@angular/build": "22.0.0-rc.0",
-      "@angular/ssr": "22.0.0-rc.0",
-      "@angular-devkit/architect": "0.2200.0-rc.0",
-      "@angular-devkit/build-angular": "22.0.0-rc.0",
-      "@angular-devkit/build-webpack": "0.2200.0-rc.0",
-      "@angular-devkit/core": "22.0.0-rc.0",
-      "@angular-devkit/schematics": "22.0.0-rc.0"
+      "@angular/cli": "22.0.0-rc.2",
+      "@angular/build": "22.0.0-rc.2",
+      "@angular/ssr": "22.0.0-rc.2",
+      "@angular-devkit/architect": "0.2200.0-rc.2",
+      "@angular-devkit/build-angular": "22.0.0-rc.2",
+      "@angular-devkit/build-webpack": "0.2200.0-rc.2",
+      "@angular-devkit/core": "22.0.0-rc.2",
+      "@angular-devkit/schematics": "22.0.0-rc.2"
     }
   },
   "repository": {
@@ -52,7 +52,7 @@
     "url": "git+https://github.com/angular/angular-cli.git"
   },
   "engines": {
-    "node": "^22.22.0 || ^24.13.1 || >=26.0.0",
+    "node": "^22.22.3 || ^24.15.0 || >=26.0.0",
     "npm": "^6.11.0 || ^7.5.6 || >=8.0.0",
     "yarn": ">= 1.13.0"
   },

package/src/commands/mcp/ARCHITECTURE.md

@@ -0,0 +1,117 @@
+# Comprehensive Architecture Review & Analysis: Angular CLI MCP Server
+
+The Model Context Protocol (MCP) server implementation within the Angular CLI (`packages/angular/cli/src/commands/mcp`) represents a state-of-the-art bridge between AI assistants (LLMs/agents) and the Angular development ecosystem. 
+
+Rather than forcing AI assistants to rely on generic, error-prone shell execution tools (`run_shell_command`), the Angular CLI MCP server exposes a highly structured, secure, and context-aware suite of tools. It encapsulates complex Angular workflows—such as monorepo project discovery, background dev server management, headless testing, AST-based migrations, and RAG-assisted documentation lookups—into clean, programmatic APIs.
+
+Below is a detailed architectural review and analysis of the implementation, broken down by core infrastructure, tool subsystems, architectural strengths, and potential areas for future enhancement.
+
+---
+
+## 1. High-Level Architecture & Security Model
+
+```
+┌──────────────────────────────────────────────────────────────────────────┐
+│                        McpCommandModule (cli.ts)                         │
+│       Handles Yargs CLI flags (--read-only, --local-only, --exp)         │
+└────────────────────────────────────┬─────────────────────────────────────┘
+                                     ▼
+┌──────────────────────────────────────────────────────────────────────────┐
+│                        McpServer Initialization                          │
+│   Configures Capabilities (tools, resources, roots, sampling, logging)   │
+└────────────────────────────────────┬─────────────────────────────────────┘
+                                     ▼
+┌──────────────────────────────────────────────────────────────────────────┐
+│                    Root-Restricted Host (host.ts)                        │
+│   Sandboxes fs/child_process to client roots; resolves local ng binary   │
+└────────────────────────────────────┬─────────────────────────────────────┘
+                                     ▼
+┌──────────────────────────────────────────────────────────────────────────┐
+│               Tool Registry & Context (tool-registry.ts)                 │
+│    Assembles Stable & Experimental tools; injects Host & Devserver Map   │
+└────────────────────────────────────┬─────────────────────────────────────┘
+                                     ▼
+┌──────────────────────────────────────────────────────────────────────────┐
+│                    Specialized Tool Implementations                      │
+│  [Projects]  [Devserver]  [Build/Test/E2E]  [Doc Search]  [Migrations]   │
+└──────────────────────────────────────────────────────────────────────────┘
+```
+
+### Command Module & Lifecycle (`cli.ts`, `mcp-server.ts`)
+* **Interactive vs. Programmatic Execution**: The CLI command checks `isTTY()`. If a user runs `ng mcp` directly in an interactive terminal, it gracefully outputs a JSON configuration snippet demonstrating how to configure an MCP client (e.g., Claude Desktop, Cursor) to attach the server via `npx -y @angular/cli mcp`. When run in a non-TTY environment, it establishes an MCP `StdioServerTransport`.
+* **Granular Security Flags**: It supports `--read-only` and `--local-only` flags. `assembleToolDeclarations` filters registered tools dynamically based on declarative tool properties (`tool.isReadOnly`, `tool.isLocalOnly`).
+* **Server Instructions**: The server initializes with robust, overarching system instructions (`instructions` capability) that orient the LLM on mandatory workflows, such as discovering project structure first (`list_projects`) and fetching version-specific coding standards (`get_best_practices`).
+
+### Sandboxed Host Abstraction (`host.ts`)
+To ensure safe execution within arbitrary client environments, all operating system and filesystem interactions are routed through a concrete `Host` interface (`LocalWorkspaceHost`), wrapped by `createRootRestrictedHost`.
+* **Dynamic Root Restriction**: The server negotiates the `roots` capability with the MCP client. It resolves allowed workspace roots via `server.server.listRoots()` and actively listens for `RootsListChangedNotificationSchema` to dynamically update the sandboxed boundaries.
+* **Path Traversal Prevention**: Every filesystem operation (`stat`, `existsSync`, `readFile`, `glob`) and process execution (`executeNgCommand`, `startNgProcess`) is validated against the allowed roots. It uses `realpathSync` to resolve symlinks and strictly rejects any relative path traversal (`..`) or absolute paths escaping the root hierarchy.
+* **Smart Local Binary Resolution**: `resolveNgCommand` uses `createRequire` from the target working directory's `package.json` to locate `@angular/cli/package.json` and resolve the local `ng.js` binary executed via `process.execPath`. This ensures that background builds and tests always run using the exact Angular CLI version installed in the workspace rather than relying on a potentially mismatched global `ng` binary.
+
+---
+
+## 2. Deep Dive into Tool Subsystems
+
+### A. Project & Workspace Discovery (`projects.ts`)
+The `list_projects` tool serves as the foundational entry point for the AI assistant to understand the workspace layout.
+* **High-Performance BFS Traversal**: Instead of naive recursive directory searching (which risks call-stack limits or memory bloat), `findAngularJsonFiles` implements an iterative, queue-based Breadth-First Search with a strict concurrency limit (`CONCURRENCY_LIMIT = 50`) to prevent file descriptor exhaustion (`EMFILE` errors).
+* **Symlink & Loop Defense**: It tracks visited directory inodes (`seenInodes`) to prevent infinite loops in complex symlinked monorepos while validating that symlink targets remain within allowed MCP roots. It explicitly skips irrelevant heavy directories (`node_modules`, `dist`, `out`, `coverage`).
+* **Intelligent Project Heuristics**:
+  * **Test Framework Detection**: `getUnitTestFramework` inspects target builders. It distinguishes between modern `@angular/build:unit-test` (parsing the `runner` option for `karma` vs. `vitest`) and older builders (`karma`, `jest`, `web-test-runner`).
+  * **Style Language Heuristics**: `getProjectStyleLanguage` evaluates project-level schematics, workspace-level schematics, build target `inlineStyleLanguage`, explicit `styles` arrays, and finally probes the filesystem for `styles.(scss|sass|less|css)`.
+  * **Framework Versioning**: `findAngularCoreVersion` traverses upwards looking for `@angular/core` in `package.json` to determine the major framework version, caching intermediate paths to optimize monorepo scanning.
+
+### B. Development Server Management (`devserver.ts`, `devserver-*.ts`)
+Managing long-running background processes over a request-response protocol like MCP requires sophisticated state handling.
+* **Stateful Process Map**: `tool-registry.ts` injects a shared `devservers` Map into the tool context, tracking active `LocalDevserver` instances keyed by `workspacePath:projectName`.
+* **Stream Parsing & Build Tracking**: `LocalDevserver` spawns `ng serve` as a background child process. It attaches listeners to `stdout`/`stderr` to monitor build lifecycle strings (`BUILD_SUCCEEDED_MESSAGE`, `BUILD_FAILED_MESSAGE`, `CHANGES_DETECTED_START_MESSAGE`). This allows the server to maintain an accurate `isBuilding()` state and cache the latest build logs.
+* **Synchronous Rebuild Verification (`devserver.wait_for_build`)**: LLMs often struggle with asynchronous file watchers. This tool allows the AI to edit a file and immediately call `devserver.wait_for_build`. The tool polls `devserver.isBuilding()` (with a `WATCH_DELAY` of 1000ms and configurable timeout), blocking until the live rebuild completes and returning the fresh build status and logs.
+* **Automated Port Assignment**: If a port is not provided, `host.getAvailablePort()` spins up a temporary TCP server on port `0` to let the OS assign a guaranteed free port, closing it immediately before launching `ng serve`.
+
+### C. Build, Test, and E2E Runners (`build.ts`, `test.ts`, `e2e.ts`)
+These one-off execution tools wrap `ng build`, `ng test`, and `ng e2e` with smart environment adaptations:
+* **Build Tool**: Defaults to the `development` configuration (unlike standard `ng build` which defaults to `production`), ensuring faster feedback loops for the AI. It parses the execution logs for `Output location: (.*)` to return the exact artifact path.
+* **Test Tool**: Automatically configures headless execution to ensure non-interactive compatibility. If the builder is `@angular/build:unit-test` (Vitest), it appends `--headless true`. For Karma-based runners, it appends `--browsers ChromeHeadless`. It forces `--watch false` and supports granular `--filter` execution.
+* **E2E Tool**: Includes pre-execution verification, checking the `angular.json` AST/model to ensure an `e2e` target actually exists before attempting execution, providing informative error messages if setup is required.
+
+### D. Documentation Search (`doc-search.ts`)
+The `search_documentation` tool provides RAG capabilities by querying official `angular.dev` documentation via Algolia.
+* **Secure API Key Decryption**: To prevent scraping or abuse of the Algolia search key, the key is stored in an encrypted form (`constants.ts`) and decrypted at runtime using `node:crypto` `createDecipheriv` (AES-256-GCM).
+* **Version Clamping & Safe Harbor**: It aligns queries with the user's local Angular major version. It clamps minimum versions to v17 (`MIN_SUPPORTED_DOCS_VERSION`). To prevent race conditions when a new major Angular version is released before its Algolia index is fully published, it implements a fallback to a hardcoded stable safe harbor (`LATEST_KNOWN_DOCS_VERSION = 20`).
+* **Stream-Based HTML Rewriting**: When `includeTopContent` is requested, it fetches the top hit URL (strictly validating the hostname is `angular.dev` or `*.angular.dev`). To avoid overwhelming the LLM's context window with bloated HTML (navigation, sidebars, footers), it uses `parse5-html-rewriting-stream` to stream and extract *only* the inner text of the `<main>` DOM element.
+
+### E. AI Tutor & Best Practices (`ai-tutor.ts`, `best-practices.ts`, `BUILD.bazel`)
+* **Prompt & Persona Injection**: The `ai_tutor` tool acts as a RAG source that injects a specialized curriculum. It leverages MCP annotations (`annotations: { audience: ['assistant'], priority: 1.0 }`) to instruct the client to treat the content as high-priority system instructions rather than displaying it to the user.
+* **Version-Aware Standards**: `get_best_practices` inspects the user's installed `@angular/core/package.json` for custom `angular.bestPractices` metadata to load version-matched guidelines. If missing or if path traversal/size limits (>1MB) are breached, it falls back to a generic guide bundled directly into the CLI package via Bazel genrules (`BUILD.bazel`).
+
+### F. OnPush & Zoneless Migration (`zoneless-migration.ts` & Subsystem)
+This subsystem provides an advanced, AST-driven refactoring workflow designed for iterative execution (one actionable step at a time).
+* **TypeScript AST Categorization**: It uses the TypeScript Compiler API (`ts-utils.ts`) to parse source files and categorize them into `zoneFiles` (containing unsupported `NgZone` imports), `filesWithComponents` (lacking `OnPush`), and `componentTestFiles`.
+* **Advanced MCP Client Sampling (`sampling/createMessage`)**: In an elegant display of advanced MCP capabilities, when multiple component files require migration, `rankComponentFilesForMigration` invokes the MCP `sampling/createMessage` request. It asks the LLM client to evaluate the file list and rank them so that shared/common components (`shared/`, `common/`, `ui/`) are migrated first.
+* **Granular Prompting**: It provides highly specific, diff-illustrated refactoring prompts for replacing `onMicrotaskEmpty`/`onStable` with `afterNextRender`/`afterEveryRender`, converting state to Signals or `markForCheck()`, and debugging test failures (`ExpressionChangedAfterItHasBeenCheckedError`).
+
+---
+
+## 3. Summary of Architectural Strengths
+
+1. **Flawless MCP Specification Alignment**: The implementation takes full advantage of the MCP specification, utilizing Tool Annotations (`readOnlyHint`, `openWorldHint`, `audience`, `priority`), Client Sampling (`sampling/createMessage`), Dynamic Roots (`listRoots`), and Stdio lifecycle management.
+2. **Defensive & Resilient Design**: The codebase exhibits rigorous defensive programming. It includes strict sandboxing in `host.ts`, inode cycle detection in `projects.ts`, fallback safe-harbor versioning in `doc-search.ts`, and graceful handling of ignorable filesystem locks/permission errors (`EACCES`, `EPERM`, `EBUSY`).
+3. **Token & Context Optimization**: Recognizing the bandwidth and context constraints of LLMs, the server avoids dumping raw data. It filters out non-essential files, streams only `<main>` content from documentation web pages, and forces iterative, single-action responses during complex migrations.
+
+---
+
+## 4. Potential Limitations & Recommendations for Future Enhancement
+
+While the implementation is exceptionally robust, a thorough analysis reveals a few edge cases and opportunities for refinement:
+
+### 1. Devserver Log Matching Fragility
+* **Observation**: In `devserver.ts`, `addLog()` evaluates build status using exact string matching (`log.startsWith(BUILD_SUCCEEDED_MESSAGE)`). If the underlying Angular CLI builder output includes ANSI color codes, terminal escape sequences, or if log formatting changes in future CLI releases, `log.startsWith` may fail to match, leaving the server in an incorrect `isBuilding() = true` state.
+* **Recommendation**: Strip ANSI codes from incoming data chunks before matching, or better yet, configure the child process to use a structured JSON IPC/logging mechanism if supported by the Angular CLI dev server builder.
+
+### 2. Global Binary Fallback Risk
+* **Observation**: In `host.ts`, `resolveNgCommand` attempts to find the local `ng.js` binary. If `createRequire` fails (e.g., in an unusual monorepo or hoisting setup), it falls back to `{ command: 'ng', args }`. If the host environment lacks a globally installed `@angular/cli` or has an outdated global version, process execution will fail unexpectedly.
+* **Recommendation**: When local resolution fails, verify the existence of global `ng` via `where`/`which` or inspect `node_modules/.bin/ng` before falling back, providing a clear diagnostic warning to the logger if a global binary fallback is triggered.
+
+### 3. AST Decorator Matching in Migrations
+* **Observation**: In `migrate-single-file.ts`, the AST visitor explicitly checks for `ts.isDecorator(node)` where the expression is a call to `Component`. If an enterprise codebase aliases the `@Component` decorator, wraps it in a custom decorator (e.g., `@CustomUIComponent`), or relies on intermediate base class inheritance for change detection strategies, the migration tool will bypass the file.
+* **Recommendation**: Utilize the TypeScript type checker (if a full program can be cheaply instantiated) to resolve base classes/decorator aliases, or expand the AST heuristic to inspect imported decorator aliases.

package/src/commands/mcp/DESIGN.md

@@ -0,0 +1,266 @@
+# Architectural Design Document: Evolving the Angular CLI MCP Server
+
+**Title**: Unified Target Execution, Structured Feedback & Generalized Watch Management  
+**Status**: Proposed / Architectural Roadmap  
+**Author**: Antigravity AI Assistant  
+**Target Area**: `packages/angular/cli/src/commands/mcp`
+
+---
+
+## 1. Executive Summary & Problem Statement
+
+The initial implementation of the Angular CLI Model Context Protocol (MCP) server successfully established a secure, programmatic sandbox for AI assistants. However, as AI agent workflows mature, four distinct architectural bottlenecks have emerged:
+
+1. **Tool Proliferation & Schema Bloat**: Hardcoding separate MCP tools (`build`, `test`, `e2e`, `devserver.start`, `devserver.stop`, `devserver.wait`) for individual Angular CLI commands increases the tool registry size. This inflates the system prompt token overhead on every LLM request and forces schema divergence for overlapping flags.
+2. **Opaque Workspace Capabilities**: The foundational `list_projects` tool exposes project roots and test frameworks but omits configured architectural targets (e.g., `lint`, `e2e`, `prerender`, `deploy`, `storybook`). This forces AI agents into an inefficient "guess and check" execution pattern.
+3. **Unstructured Log Dumping**: The `logs` output across existing tools is currently populated by raw OS stream chunks (`data.toString()`). These chunks contain partial lines, ANSI color escapes, and progress spinner artifacts (`\r`). When JSON-escaped, this raw stream becomes exceptionally difficult and token-heavy for LLMs to parse, undermining the goal of providing structured data.
+4. **Fragmented Watch Mode Management**: Watch mode is currently restricted entirely to `ng serve` via the `devserver.*` toolset. There is no generalized mechanism to support long-running watched builds (`ng build --watch`) or watched unit tests (`ng test --watch`), limiting the AI's ability to receive rapid, iterative feedback across different target types.
+
+---
+
+## 2. Proposed Architectural Vision
+
+We propose evolving the MCP server toward a unified, target-driven architecture that mirrors Angular’s native `architect` model (**Workspace ➔ Project ➔ Target ➔ Builder**). 
+
+By pairing declarative target discovery in `list_projects` with a unified `run_target` facade, structured JSON reporters, and a generalized `WatchedTargetManager`, the server will achieve ultimate scalability, massive token savings, and pinpoint diagnostic accuracy across both one-off and long-running execution modes.
+
+```
+┌──────────────────────────────────────────────────────────────────────────┐
+│                        Declarative AI Workflow                           │
+│                                                                          │
+│  1. list_projects ──> Returns metadata + targets: ['build', 'test']      │
+│  2. Code Edit     ──> AI performs workspace modifications                │
+│  3. run_target    ──> { project: 'app', target: 'test', watch: true }    │
+└────────────────────────────────────┬─────────────────────────────────────┘
+                                     ▼
+┌──────────────────────────────────────────────────────────────────────────┐
+│                   Target Dispatcher (Strategy Pattern)                   │
+│           Inspects target name & builder from angular.json AST           │
+└────────────────────┬───────────────┬───────────────┬─────────────────────┘
+                     ▼               ▼               ▼
+            ┌─────────────────┐┌───────────┐┌──────────────────┐
+            │ UnitTestHandler ││E2EHandler ││  BuildHandler    │ ... [Custom]
+            └────────┬────────┘└─────┬─────┘└────────┬─────────┘
+                     ▼               ▼               ▼
+            ┌─────────────────┐┌───────────┐┌──────────────────┐
+            │Vitest JSON Parse││Cypress/PW ││Parse Output Path │ ... [Sanitized]
+            └────────┬────────┘└─────┬─────┘└────────┬─────────┘
+                     ▼               ▼               ▼
+┌──────────────────────────────────────────────────────────────────────────┐
+│            WatchedTargetManager (If watch: true requested)               │
+│    Maintains active background processes & broadcasts rebuild events     │
+└──────────────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## 3. Detailed Component Design
+
+### 3.1 Declarative Target Discovery (`list_projects`)
+Update `listProjectsOutputSchema` and `loadAndParseWorkspace` in `projects.ts` to extract and expose configured architect targets for each project.
+
+```typescript
+// Proposed addition to listProjectsOutputSchema
+projects: z.array(
+  z.object({
+    name: z.string(),
+    root: z.string(),
+    sourceRoot: z.string(),
+    projectType: z.enum(['application', 'library']).optional(),
+    unitTestFramework: z.enum(['jasmine', 'jest', 'vitest', 'unknown']).optional(),
+    // NEW: Array of available architect target names
+    targets: z.array(z.string()).describe('Available architect targets (e.g., ["build", "test", "lint", "e2e"])'),
+  })
+)
+```
+* **AI Impact**: Eliminates blind execution. An AI can immediately verify if `e2e` or `lint` is supported before attempting execution.
+
+### 3.2 Stream Sanitization & Structured Reporters
+To solve the unstructured log dumping problem, we establish a dual-horizon reporting architecture:
+
+#### Near-Term: Stream Sanitization (`host.ts`)
+Modify `executeNgCommand` in `host.ts` to buffer incoming `stdout`/`stderr` streams, split them cleanly by newlines (`\n`), and strip out ANSI color escapes and carriage returns (`\r`). 
+```typescript
+// Conceptual sanitization buffer
+const cleanLogs: string[] = rawStreamBuffer
+  .split('\n')
+  .map(line => line.replace(/\x1B\[\d+m|\r/g, '').trim())
+  .filter(line => line.length > 0);
+```
+
+#### Long-Term: Structured JSON Reporters (`test.ts`, `e2e.ts`)
+Instead of capturing `stdout` for verification workflows, configure the underlying runners to generate structured JSON summaries. The MCP tool parses the JSON artifact and returns a concise, semantic contract to the LLM:
+```json
+{
+  "status": "failure",
+  "summary": {
+    "total": 25,
+    "passed": 24,
+    "failed": 1
+  },
+  "failures": [
+    {
+      "spec": "auth.component.spec.ts",
+      "test": "should redirect on expired token",
+      "errorMessage": "Expected status 302, but received 200."
+    }
+  ]
+}
+```
+
+### 3.3 The Unified `run_target` Facade
+Deprecate standalone `build`, `test`, and `e2e` tools in favor of a single `run_target` MCP tool declaration.
+
+```typescript
+const runTargetInputSchema = z.object({
+  workspace: z.string().optional(),
+  project: z.string().optional(),
+  target: z.string().describe('The architect target to execute (e.g., "build", "test", "lint", "e2e", "deploy")'),
+  configuration: z.string().optional().describe('Target configuration (e.g., "development", "production")'),
+  options: z.record(z.unknown()).optional().describe('Optional key-value flags to pass to the builder (e.g., { watch: true, instanceId: "preview" })'),
+});
+```
+
+#### The Strategy Dispatcher (`TargetDispatcher`)
+Under the hood, `run_target` implements the Strategy Pattern to route execution based on the target name and underlying builder definition:
+
+1. **`UnitTestStrategy` (Target: `test`)**:
+   * Inspects builder (`@angular/build:unit-test` vs Karma).
+   * Automatically injects `--headless true` or `--browsers ChromeHeadless`.
+   * Attaches JSON reporter and returns structured semantic test results.
+2. **`E2EStrategy` (Target: `e2e`)**:
+   * Inspects builder (`@cypress/schematic:cypress`, `@playwright/test`).
+   * Injects CI/headless execution flags.
+   * Parses runner JSON summary and returns structured E2E results.
+3. **`BuildStrategy` (Target: `build`)**:
+   * Defaults to `development`.
+   * Parses output logs for `Output location: (.*)` to return exact artifact paths.
+4. **`LintStrategy` (Target: `lint`)**:
+   * Injects `--format json`.
+   * Parses ESLint output and returns structured file/line error diagnostics.
+5. **`GenericStrategy` (Target: Custom / Unknown)**:
+   * Executes custom community builders (e.g., `storybook`, `prerender`, `compodoc`).
+   * Returns sanitized, line-buffered `stdout`/`stderr`.
+
+---
+
+### 3.4 Generalized Watch Mode Management (`WatchedTargetManager`)
+To support long-running, watched execution across all target types (e.g., `ng serve`, `ng build --watch`, `ng test --watch`), we transition from the legacy `devservers` Map to a generalized `WatchedTargetManager`.
+
+We evaluated three architectural approaches for exposing watch mode management to AI agents:
+
+#### Approach 1: The `watchMode` Lifecycle Flag (Single-Tool Encapsulation)
+`run_target` remains the exclusive tool, using a `watchMode: 'start' | 'wait' | 'stop' | 'none'` parameter to manage the background lifecycle.
+* **Pros**: Absolute minimal tool registry size (exactly one tool).
+* **Cons**: Overloads the `run_target` schema. The LLM must understand the stateful `start ➔ wait ➔ stop` sequence via parameter flags.
+
+#### Approach 2: Dedicated Companion Tools (Separation of Concerns)
+`run_target` is used purely for spawning (`watch: true`), while two generalized companion tools manage active background jobs.
+```
+┌──────────────────────────────────────────────────────────────────────────┐
+│                   run_target { ..., watch: true }                        │
+│         Spawns process & registers in context.watchedTargets Map         │
+└────────────────────────────────────┬─────────────────────────────────────┘
+                                     ▼
+┌──────────────────────────────────────────────────────────────────────────┐
+│             watched_target.wait { project: 'app', target: 'serve' }      │
+│           Blocks until active rebuild completes; returns fresh logs      │
+├──────────────────────────────────────────────────────────────────────────┤
+│             watched_target.stop { project: 'app', target: 'serve' }      │
+│                 Terminates background process & cleans Map               │
+└──────────────────────────────────────────────────────────────────────────┘
+```
+* **Pros**: Keeps `run_target` input schema extremely clean. Clear separation of concerns between spawning work and inspecting active background jobs.
+* **Cons**: Adds 2 companion tools to the registry (`watched_target.wait`, `watched_target.stop`).
+
+#### Approach 3: MCP Server Push / Notifications (The Reactive Agent Horizon)
+Instead of the AI actively polling via a `wait` tool, the server pushes custom MCP notifications (e.g., `notifications/target_watch_event`) containing structured rebuild summaries whenever the OS file watcher triggers a background rebuild.
+* **Pros**: True asynchronous elegance. Completely eliminates active polling (`wait_for_build`) and saves significant tool-calling overhead.
+* **Cons**: Requires the MCP client (Cursor, Claude Desktop, custom agent runner) to support and react to custom server notifications.
+
+#### Watch Mode Comparative Summary & Architectural Verdict
+
+| Dimension | Approach 1 (`watchMode` Flag) | Approach 2 (Companion Tools) | Approach 3 (MCP Notifications) |
+| :--- | :--- | :--- | :--- |
+| **Tool Registry Size** | **1 Tool** (Lowest) | **3 Tools** (Moderate) | **1 Tool** (Lowest) |
+| **LLM Schema Complexity** | Moderate (Union flags) | **Low** (Clean separation) | **Low** (Clean separation) |
+| **Client Compatibility** | **Universal** (All MCP clients) | **Universal** (All MCP clients) | **Restricted** (Requires notification support) |
+| **Execution Overhead** | Requires polling (`wait`) | Requires polling (`wait`) | **Zero Polling** (Reactive push) |
+
+**Architectural Recommendation**:  
+For immediate compatibility with existing MCP clients (which primarily rely on request/response tool calling), **Approach 2 (Dedicated Companion Tools)** is the most ergonomic and reliable choice. It keeps tool schemas clean while providing a clear, predictable contract for LLMs.
+
+However, the underlying `WatchedTargetManager` should be designed to emit internal event streams. This ensures the server is perfectly positioned to adopt **Approach 3 (MCP Notifications)** as agentic platforms evolve to support reactive notification wakeups.
+
+---
+
+## 3.5 Multi-Instance Watch Mode & Configuration Clobbering
+A critical edge case in AI agent workflows is handling multiple watch mode requests for the exact same target (e.g., calling `run_target({ project: 'app', target: 'serve', watch: true })` multiple times with different ports or flags).
+
+To provide an exceptionally ergonomic, self-healing experience, the `WatchedTargetManager` implements a **Smart Hybrid** tracking strategy:
+
+```
+┌──────────────────────────────────────────────────────────────────────────┐
+│          AI Agent calls run_target { project: 'app', target: 'serve' }   │
+└────────────────────────────────────┬─────────────────────────────────────┘
+                                     ▼
+┌──────────────────────────────────────────────────────────────────────────┐
+│              Does active process exist for app:serve:default?            │
+└────────────────────┬───────────────────────────────┬─────────────────────┘
+                     │ YES                           │ NO
+                     ▼                               ▼
+┌────────────────────────────────────────┐ ┌───────────────────────────────┐
+│     Are requested options identical?   │ │ Spawn fresh process & store   │
+└─────────┬────────────────────┬─────────┘ └───────────────────────────────┘
+          │ YES                │ NO (e.g. new port/config)
+          ▼                    ▼
+┌────────────────────┐ ┌───────────────────────────────────────────────────┐
+│ Idempotent No-Op   │ │ Graceful Restart (Clobber)                        │
+│ Return active URL  │ │ Auto-kill old process & spawn fresh with new flags│
+└────────────────────┘ └───────────────────────────────────────────────────┘
+```
+
+1. **Default Idempotency (If options match)**: If the AI calls `run_target` again with the *exact same options*, treat it as an idempotent no-op. Return the active process status/address immediately without incurring a restart penalty.
+2. **Auto-Clobbering (If options differ)**: If the AI calls `run_target` again with *different options* (e.g., a new port or configuration flag), automatically terminate the old process and spawn a fresh one. This provides seamless self-healing without requiring the LLM to manually call `watched_target.stop`.
+3. **Explicit Concurrency (If `instanceId` provided)**: If the AI explicitly provides an `instanceId` in the options (e.g., `instanceId: 'preview'` vs `instanceId: 'e2e'`), isolate the process in the internal map (`workspace:project:target:instanceId`), allowing side-by-side execution of the same target.
+
+---
+
+## 4. Summary of Architectural Advantages
+
+| Metric | Current Architecture | Proposed Architecture (`run_target` + Companion Tools) |
+| :--- | :--- | :--- |
+| **Tool Registry Size** | Multiple growing tools (`build`, `test`, `e2e`, `devserver.*`) | **Exactly Three Tools** (`run_target`, `watched_target.wait`, `watched_target.stop`) |
+| **LLM Prompt Overhead** | High (multiple verbose tool definitions) | **Minimal** (clean, modular tool definitions) |
+| **Target Discovery** | Opaque (guess and check) | **Declarative** (exposed via `list_projects`) |
+| **Log Parsing Ergonomics**| Poor (JSON-escaped raw stream chunks) | **Excellent** (Structured JSON summaries & clean lines) |
+| **Watch Mode Scope** | Restricted to `ng serve` only | **Universal** (supports watched builds, tests, and custom targets) |
+| **Multi-Instance Watch**| Idempotent no-op only (rigid) | **Smart Hybrid** (idempotent reuse + auto-clobbering + aliasing) |
+| **Extensibility** | Requires new MCP tool code per command | **Instant** (supports all custom builders via generic fallback) |
+
+---
+
+## 5. LLM Ergonomics & Context Window Optimization
+
+Exposing numerous granular tools to an LLM introduces significant technical and cognitive overhead. Evolving to the unified `run_target` design directly optimizes how AI assistants consume the MCP server within their context constraints:
+
+### 5.1 System Prompt Token Footprint
+MCP clients inject tool names, descriptions, and JSON parameter schemas directly into the system prompt of every query. A single, highly descriptive tool averages **200 to 500 tokens** of overhead.
+* **Granular Architecture (8+ Tools)**: Creates a permanent tax of **1,600 to 4,000 tokens** on every single user query.
+* **Unified Architecture (3 Tools)**: Slashes this permanent tax down to **600 to 1,500 tokens** (a **60%+ permanent reduction**), maximizing the remaining context window for actual project files and code analysis.
+
+### 5.2 Attention Window & Selection Accuracy
+LLMs utilize attention mechanisms that suffer from **"Lost in the Middle"** retrieval degradation when presented with massive, flat lists of choices (15+ tools). Tool selection accuracy drops significantly in the middle of a long prompt.
+Furthermore, exposing overlapping tools (e.g., separate `build`, `test_unit`, `test_e2e`) leads to semantic blur, causing the LLM to hallucinate parameters or select incorrect tools. Collapsing the entire workspace capabilities into exactly three semantically distinct axes (`list_projects` for discovery, `run_target` for execution, `watched_target` for background lifecycles) ensures **near-100% tool selection accuracy** and eliminates parameter clashing.
+
+---
+
+## 6. Execution Roadmap
+
+1. **Step 1**: Update `projects.ts` to include `targets: z.array(z.string())` in the `list_projects` output schema. [**Completed**]
+2. **Step 2**: Implement stream line buffering, native VT-stripping, and process deduplication in `host.ts`. [**Completed**]
+3. **Step 3**: Implement the `run_target` tool declaration and the base Strategy Dispatcher.
+4. **Step 4**: Migrate `build.ts`, `test.ts`, and `e2e.ts` logic into their respective internal Strategy Handlers (`BuildStrategy`, `UnitTestStrategy`, `E2EStrategy`).
+5. **Step 5**: Implement `WatchedTargetManager` with the Smart Hybrid tracking strategy (idempotency, clobbering, aliasing).
+6. **Step 6**: Implement `watched_target.wait` and `watched_target.stop` companion tools.
+7. **Step 7**: Deprecate legacy standalone tool declarations (`build`, `test`, `e2e`, `devserver.*`) from `mcp-server.ts`.