diff --git a/goldens/public-api/angular/build/index.api.md b/goldens/public-api/angular/build/index.api.md index 6ef310c78e9e..e313c42628c5 100644 --- a/goldens/public-api/angular/build/index.api.md +++ b/goldens/public-api/angular/build/index.api.md @@ -122,6 +122,7 @@ export type DevServerBuilderOptions = { host?: string; inspect?: Inspect; liveReload?: boolean; + manualRebuild?: boolean; open?: boolean; poll?: number; port?: number; diff --git a/packages/angular/build/src/builders/application/build-action.ts b/packages/angular/build/src/builders/application/build-action.ts index d03d2741b105..96b739d065ad 100644 --- a/packages/angular/build/src/builders/application/build-action.ts +++ b/packages/angular/build/src/builders/application/build-action.ts @@ -19,6 +19,7 @@ import { } from '../../tools/esbuild/stylesheets/sass-language'; import { logMessages, withNoProgress, withSpinner } from '../../tools/esbuild/utils'; import { initializeHash } from '../../utils/hash'; +import type { ManualRebuildController, ManualRebuildResult } from '../../utils/manual-rebuild'; import { NormalizedCachedOptions } from '../../utils/normalize-cache'; import { ChangedFiles } from '../../utils/watcher'; import { NormalizedApplicationBuildOptions, NormalizedOutputOptions } from './options'; @@ -50,6 +51,7 @@ export async function* runEsBuildBuildAction( colors?: boolean; jsonLogs?: boolean; incrementalResults?: boolean; + manualRebuild?: ManualRebuildController; }, ): AsyncIterable { const { @@ -67,6 +69,7 @@ export async function* runEsBuildBuildAction( colors, jsonLogs, incrementalResults, + manualRebuild, } = options; await initializeHash(); @@ -95,6 +98,11 @@ export async function* runEsBuildBuildAction( if (watch) { if (progress) { logger.info('Watch mode enabled. Watching for file changes...'); + if (manualRebuild) { + logger.info( + 'Manual rebuild mode enabled. File changes will be rebuilt only when a rebuild is requested.', + ); + } } // Setup a watcher @@ -140,8 +148,29 @@ export async function* runEsBuildBuildAction( // Wait for changes and rebuild as needed const currentWatchFiles = new Set(result.watchFiles); + let rebuilds: AsyncIterable<{ + changes: ChangedFiles; + requests?: ((result: ManualRebuildResult) => void)[]; + }>; + if (manualRebuild) { + const { waitForManualRebuilds } = await import('../../utils/manual-rebuild'); + rebuilds = waitForManualRebuilds(watcher, manualRebuild, { + onChangesPending: () => { + if (progress) { + logger.info('File changes detected. Waiting for a rebuild request...'); + } + }, + }); + } else { + rebuilds = mapChanges(watcher); + } + + // Manual rebuild requests for the rebuild in progress. These are resolved as cancelled if the + // loop exits before the rebuild completes (e.g., abort signal, build error, or consumer exit). + let activeRequests: ((result: ManualRebuildResult) => void)[] | undefined; try { - for await (const changes of watcher) { + for await (const { changes, requests } of rebuilds) { + activeRequests = requests; if (options.signal?.aborted) { break; } @@ -202,8 +231,24 @@ export async function* runEsBuildBuildAction( // Clear initial build errors flag if no errors are now present hasInitialErrors &&= result.errors.length > 0; + + // Notify any manual rebuild requesters now that all results have been emitted + if (requests?.length) { + const status = result.errors.length > 0 ? 'failure' : 'success'; + for (const resolve of requests) { + resolve({ status }); + } + } + activeRequests = undefined; } } finally { + if (activeRequests) { + for (const resolve of activeRequests) { + resolve({ status: 'cancelled' }); + } + } + manualRebuild?.close(); + // Stop the watcher and cleanup incremental rebuild state await Promise.allSettled([watcher.close(), result.dispose()]); @@ -211,6 +256,14 @@ export async function* runEsBuildBuildAction( } } +async function* mapChanges( + watcher: AsyncIterable, +): AsyncIterable<{ changes: ChangedFiles }> { + for await (const changes of watcher) { + yield { changes }; + } +} + function* emitOutputResults( { outputFiles, diff --git a/packages/angular/build/src/builders/application/index.ts b/packages/angular/build/src/builders/application/index.ts index db2cee237896..67ca3ee18a33 100644 --- a/packages/angular/build/src/builders/application/index.ts +++ b/packages/angular/build/src/builders/application/index.ts @@ -137,6 +137,7 @@ export async function* buildApplicationInternal( colors: normalizedOptions.colors, jsonLogs: normalizedOptions.jsonLogs, incrementalResults: normalizedOptions.incrementalResults, + manualRebuild: normalizedOptions.manualRebuild, logger, signal, }, diff --git a/packages/angular/build/src/builders/application/options.ts b/packages/angular/build/src/builders/application/options.ts index d27caa25153f..501ce2234018 100644 --- a/packages/angular/build/src/builders/application/options.ts +++ b/packages/angular/build/src/builders/application/options.ts @@ -15,6 +15,7 @@ import { supportColor } from '../../utils/color'; import { useJSONBuildLogs, usePartialSsrBuild } from '../../utils/environment-options'; import { I18nOptions, createI18nOptions } from '../../utils/i18n-options'; import { IndexHtmlTransform } from '../../utils/index-file/index-html-generator'; +import type { ManualRebuildController } from '../../utils/manual-rebuild'; import { normalizeCacheOptions } from '../../utils/normalize-cache'; import { canonicalizePath } from '../../utils/path'; import { @@ -114,6 +115,13 @@ interface InternalOptions { */ incrementalResults?: boolean; + /** + * When provided, file changes detected in watch mode do not automatically trigger a rebuild. + * Instead, accumulated changes are rebuilt incrementally only when a rebuild is requested + * via the controller. This option also requires watch to be enabled to have an effect. + */ + manualRebuild?: ManualRebuildController; + /** * Enables instrumentation to collect code coverage data for specific files. * @@ -560,6 +568,7 @@ export async function normalizeOptions( security, templateUpdates: !!options.templateUpdates, incrementalResults: !!options.incrementalResults, + manualRebuild: options.manualRebuild, customConditions: options.conditions, frameworkVersion: await findFrameworkVersion(projectRoot), }; diff --git a/packages/angular/build/src/builders/dev-server/options.ts b/packages/angular/build/src/builders/dev-server/options.ts index 71210f9d7d98..fba4b0617028 100644 --- a/packages/angular/build/src/builders/dev-server/options.ts +++ b/packages/angular/build/src/builders/dev-server/options.ts @@ -15,9 +15,10 @@ import { Schema as DevServerOptions } from './schema'; export type NormalizedDevServerOptions = Omit< Awaited>, - 'strictPort' + 'strictPort' | 'manualRebuild' > & { strictPort?: boolean; + manualRebuild?: boolean; }; /** @@ -115,6 +116,7 @@ export async function normalizeOptions( verbose, define, watch, + manualRebuild, liveReload, hmr, headers, @@ -138,6 +140,7 @@ export async function normalizeOptions( verbose, define, watch, + manualRebuild: !!manualRebuild, liveReload: !!liveReload, hmr: hmr ?? !!liveReload, headers, diff --git a/packages/angular/build/src/builders/dev-server/schema.json b/packages/angular/build/src/builders/dev-server/schema.json index 667bde5692da..cc41a49510d8 100644 --- a/packages/angular/build/src/builders/dev-server/schema.json +++ b/packages/angular/build/src/builders/dev-server/schema.json @@ -102,6 +102,11 @@ "type": "number", "description": "Enable and define the file watching poll time period in milliseconds." }, + "manualRebuild": { + "type": "boolean", + "description": "Rebuild only when explicitly requested instead of on every file change. File changes are still tracked while in watch mode, and all pending changes are rebuilt incrementally when a `POST` request is sent to the `/__ng_rebuild` endpoint of the development server or the `b` key is pressed in the terminal. This option has no effect when 'watch' is disabled.", + "default": false + }, "inspect": { "default": false, "description": "Activate debugging inspector. This option only has an effect when 'SSR' or 'SSG' are enabled.", diff --git a/packages/angular/build/src/builders/dev-server/tests/options/manual-rebuild_spec.ts b/packages/angular/build/src/builders/dev-server/tests/options/manual-rebuild_spec.ts new file mode 100644 index 000000000000..b009cadeec8d --- /dev/null +++ b/packages/angular/build/src/builders/dev-server/tests/options/manual-rebuild_spec.ts @@ -0,0 +1,94 @@ +/** + * @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 { setTimeout } from 'node:timers/promises'; +import { executeDevServer } from '../../index'; +import { describeServeBuilder } from '../jasmine-helpers'; +import { BASE_OPTIONS, DEV_SERVER_BUILDER_INFO } from '../setup'; + +const REBUILD_PATH = '__ng_rebuild'; + +describeServeBuilder(executeDevServer, DEV_SERVER_BUILDER_INFO, (harness, setupTarget) => { + describe('Option: "manualRebuild"', () => { + beforeEach(() => { + setupTarget(harness); + }); + + it('only rebuilds file changes when a rebuild is requested', async () => { + harness.useTarget('serve', { + ...BASE_OPTIONS, + watch: true, + manualRebuild: true, + }); + + let baseUrl = ''; + let rebuildResponse: Promise | undefined; + + await harness.executeWithCases([ + async ({ result }) => { + expect(result?.success).toBeTrue(); + baseUrl = result?.baseUrl as string; + + // Nothing pending so a request should not rebuild + const noChangesResponse = await fetch(new URL(REBUILD_PATH, baseUrl), { + method: 'POST', + }); + expect(noChangesResponse.status).toBe(200); + expect(await noChangesResponse.json()).toEqual({ status: 'no-changes' }); + + await harness.modifyFile( + 'src/main.ts', + (content) => content + 'console.log("abcd1234");', + ); + + // Give the file watcher enough time to detect the change. No rebuild should occur. + await setTimeout(1500); + const before = await fetch(new URL('main.js', baseUrl)); + expect(await before.text()).not.toContain('abcd1234'); + + // Request a rebuild. The response is sent once the rebuild completes. + rebuildResponse = fetch(new URL(REBUILD_PATH, baseUrl), { method: 'POST' }); + }, + async ({ result }) => { + expect(result?.success).toBeTrue(); + + const response = await rebuildResponse; + expect(response?.status).toBe(200); + expect(await response?.json()).toEqual({ status: 'success' }); + + const after = await fetch(new URL('main.js', baseUrl)); + expect(await after.text()).toContain('abcd1234'); + }, + ]); + }); + + it('rejects non-POST and cross-origin rebuild requests', async () => { + harness.useTarget('serve', { + ...BASE_OPTIONS, + watch: true, + manualRebuild: true, + }); + + await harness.executeWithCases([ + async ({ result }) => { + expect(result?.success).toBeTrue(); + const url = new URL(REBUILD_PATH, result?.baseUrl as string); + + const getResponse = await fetch(url); + expect(getResponse.status).toBe(405); + + const crossOriginResponse = await fetch(url, { + method: 'POST', + headers: { origin: 'http://example.com' }, + }); + expect(crossOriginResponse.status).toBe(403); + }, + ]); + }); + }); +}); diff --git a/packages/angular/build/src/builders/dev-server/vite/index.ts b/packages/angular/build/src/builders/dev-server/vite/index.ts index 7f36740cc3f5..42c4b44c0984 100644 --- a/packages/angular/build/src/builders/dev-server/vite/index.ts +++ b/packages/angular/build/src/builders/dev-server/vite/index.ts @@ -13,11 +13,16 @@ import { join } from 'node:path'; import type * as Vite from 'vite' with { 'resolution-mode': 'import', }; -import type { ComponentStyleRecord } from '../../../tools/vite/middlewares'; +import { + type ComponentStyleRecord, + REBUILD_ROUTE, + createAngularRebuildMiddleware, +} from '../../../tools/vite/middlewares'; import { ServerSsrMode } from '../../../tools/vite/plugins'; import { updateExternalMetadata } from '../../../tools/vite/utils'; import { normalizeSourceMaps } from '../../../utils'; import { useComponentStyleHmr, useComponentTemplateHmr } from '../../../utils/environment-options'; +import { ManualRebuildController } from '../../../utils/manual-rebuild'; import { Result, ResultKind } from '../../application/results'; import { OutputHashing } from '../../application/schema'; import { @@ -181,6 +186,18 @@ export async function* serveWithVite( browserOptions.templateUpdates = componentsHmrCanBeUsed && useComponentTemplateHmr; browserOptions.incrementalResults = true; + // Setup manual rebuild support which requires watch mode to be enabled + let manualRebuild: ManualRebuildController | undefined; + if (serverOptions.manualRebuild) { + if (browserOptions.watch) { + manualRebuild = browserOptions.manualRebuild = new ManualRebuildController(); + } else { + context.logger.warn( + `The 'manualRebuild' option has no effect because the 'watch' option is disabled.`, + ); + } + } + // Setup the prebundling transformer that will be shared across Vite prebundling requests const prebundleTransformer = new JavaScriptTransformer( // Always enable JIT linking to support applications built with and without AOT. @@ -434,7 +451,9 @@ export async function* serveWithVite( 'ngJitMode': browserOptions.aot ? 'false' : 'true', 'ngHmrMode': browserOptions.templateUpdates ? 'true' : 'false', }, - extensions?.middleware, + manualRebuild + ? [createAngularRebuildMiddleware(manualRebuild), ...(extensions?.middleware ?? [])] + : extensions?.middleware, transformers?.indexHtml, thirdPartySourcemaps, ); @@ -503,21 +522,45 @@ export async function* serveWithVite( // log connection information server.printUrls(); + if (manualRebuild && serverUrl) { + context.logger.info( + `Manual rebuild mode enabled. Send a POST request to ${new URL(REBUILD_ROUTE, serverUrl)}` + + ` or press "b" to rebuild pending changes.`, + ); + } + + const customShortcuts: Vite.CLIShortcut[] = [ + { + key: 'r', + description: 'force reload browser', + action(server) { + componentStyles.forEach((record) => record.used?.clear()); + server.ws.send({ + type: 'full-reload', + path: '*', + }); + }, + }, + ]; + + if (manualRebuild) { + const controller = manualRebuild; + customShortcuts.push({ + key: 'b', + description: 'rebuild pending changes', + action() { + void controller.requestRebuild().then(({ status }) => { + if (status === 'no-changes') { + context.logger.info('No pending changes to rebuild.'); + } + }); + }, + }); + } + server.bindCLIShortcuts({ print: true, - customShortcuts: [ - { - key: 'r', - description: 'force reload browser', - action(server) { - componentStyles.forEach((record) => record.used?.clear()); - server.ws.send({ - type: 'full-reload', - path: '*', - }); - }, - }, - ], + customShortcuts, }); } diff --git a/packages/angular/build/src/tools/vite/middlewares/index.ts b/packages/angular/build/src/tools/vite/middlewares/index.ts index 807e739eed59..917b8901a220 100644 --- a/packages/angular/build/src/tools/vite/middlewares/index.ts +++ b/packages/angular/build/src/tools/vite/middlewares/index.ts @@ -16,5 +16,6 @@ export { export { createAngularHeadersMiddleware } from './headers-middleware'; export { createAngularComponentMiddleware } from './component-middleware'; export { createChromeDevtoolsMiddleware } from './chrome-devtools-middleware'; +export { REBUILD_ROUTE, createAngularRebuildMiddleware } from './rebuild-middleware'; export { patchHostValidationMiddleware } from './host-check-middleware'; export { patchBaseMiddleware } from './base-middleware'; diff --git a/packages/angular/build/src/tools/vite/middlewares/rebuild-middleware.ts b/packages/angular/build/src/tools/vite/middlewares/rebuild-middleware.ts new file mode 100644 index 000000000000..9e0ec6def721 --- /dev/null +++ b/packages/angular/build/src/tools/vite/middlewares/rebuild-middleware.ts @@ -0,0 +1,80 @@ +/** + * @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 { Connect } from 'vite' with { + 'resolution-mode': 'import', +}; +import type { ManualRebuildController } from '../../../utils/manual-rebuild'; + +/** + * The development server route used to request a rebuild when manual rebuild mode is enabled. + */ +export const REBUILD_ROUTE = '/__ng_rebuild'; + +/** + * Creates a middleware that triggers a rebuild of all pending file changes when a `POST` request + * is sent to {@link REBUILD_ROUTE}. The response is sent once the rebuild has completed and contains + * a JSON object with the outcome of the rebuild (e.g., `{ "status": "success" }`). + * + * @param controller The controller used to request rebuilds. + * @returns A Connect middleware function. + */ +export function createAngularRebuildMiddleware( + controller: ManualRebuildController, +): Connect.NextHandleFunction { + return function angularRebuildMiddleware(req, res, next) { + const pathname = req.url?.split('?', 1)[0]; + if (pathname !== REBUILD_ROUTE) { + next(); + + return; + } + + if (req.method !== 'POST') { + res.statusCode = 405; + res.setHeader('Allow', 'POST'); + res.end(); + + return; + } + + // Reject cross-origin requests made by browsers to prevent arbitrary web pages from + // triggering rebuilds. Non-browser clients (e.g., curl or tooling) do not send an origin. + // HTTP/2 requests (used by the development server when SSL is enabled) provide the + // `:authority` pseudo-header instead of `host`. + const host = req.headers.host ?? (req.headers[':authority'] as string | undefined); + if (!isSameOrigin(req.headers.origin, host)) { + res.statusCode = 403; + res.end(); + + return; + } + + controller.requestRebuild().then( + (result) => { + res.statusCode = result.status === 'cancelled' ? 503 : 200; + res.setHeader('Content-Type', 'application/json'); + res.setHeader('Cache-Control', 'no-store'); + res.end(JSON.stringify(result)); + }, + (error) => next(error), + ); + }; +} + +function isSameOrigin(origin: string | undefined, host: string | undefined): boolean { + if (origin === undefined) { + return true; + } + + try { + return new URL(origin).host === host; + } catch { + return false; + } +} diff --git a/packages/angular/build/src/tools/vite/middlewares/rebuild-middleware_spec.ts b/packages/angular/build/src/tools/vite/middlewares/rebuild-middleware_spec.ts new file mode 100644 index 000000000000..fe947f905d38 --- /dev/null +++ b/packages/angular/build/src/tools/vite/middlewares/rebuild-middleware_spec.ts @@ -0,0 +1,135 @@ +/** + * @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 { IncomingMessage, ServerResponse } from 'node:http'; +import { ManualRebuildController } from '../../../utils/manual-rebuild'; +import { createAngularRebuildMiddleware } from './rebuild-middleware'; + +interface MockResponse { + statusCode: number; + headers: Record; + body: string | undefined; + ended: Promise; +} + +function createRequest( + url: string, + method: string, + headers: Record = {}, +): IncomingMessage { + return { url, method, headers } as unknown as IncomingMessage; +} + +function createResponse(): [ServerResponse, MockResponse] { + let resolveEnded: () => void; + const mock: MockResponse = { + statusCode: 200, + headers: {}, + body: undefined, + ended: new Promise((resolve) => (resolveEnded = resolve)), + }; + const res = { + set statusCode(value: number) { + mock.statusCode = value; + }, + setHeader(name: string, value: string) { + mock.headers[name.toLowerCase()] = value; + }, + end(body?: string) { + mock.body = body; + resolveEnded(); + }, + }; + + return [res as unknown as ServerResponse, mock]; +} + +describe('createAngularRebuildMiddleware', () => { + let controller: ManualRebuildController; + let middleware: ReturnType; + + beforeEach(() => { + controller = new ManualRebuildController(); + spyOn(controller, 'requestRebuild').and.resolveTo({ status: 'success' }); + middleware = createAngularRebuildMiddleware(controller); + }); + + it('passes through requests for other routes', () => { + const next = jasmine.createSpy('next'); + const [res] = createResponse(); + middleware(createRequest('/main.js', 'POST'), res, next); + + expect(next).toHaveBeenCalled(); + expect(controller.requestRebuild).not.toHaveBeenCalled(); + }); + + it('requests a rebuild and responds with the result', async () => { + const [res, mock] = createResponse(); + middleware(createRequest('/__ng_rebuild?x=1', 'POST'), res, jasmine.createSpy('next')); + await mock.ended; + + expect(mock.statusCode).toBe(200); + expect(mock.headers['content-type']).toBe('application/json'); + expect(JSON.parse(mock.body ?? '')).toEqual({ status: 'success' }); + }); + + it('responds with 405 for non-POST requests', async () => { + const [res, mock] = createResponse(); + middleware(createRequest('/__ng_rebuild', 'GET'), res, jasmine.createSpy('next')); + await mock.ended; + + expect(mock.statusCode).toBe(405); + expect(controller.requestRebuild).not.toHaveBeenCalled(); + }); + + it('rejects cross-origin requests', async () => { + const [res, mock] = createResponse(); + middleware( + createRequest('/__ng_rebuild', 'POST', { + host: 'localhost:4200', + origin: 'http://example.com', + }), + res, + jasmine.createSpy('next'), + ); + await mock.ended; + + expect(mock.statusCode).toBe(403); + expect(controller.requestRebuild).not.toHaveBeenCalled(); + }); + + it('accepts same-origin requests', async () => { + const [res, mock] = createResponse(); + middleware( + createRequest('/__ng_rebuild', 'POST', { + host: 'localhost:4200', + origin: 'http://localhost:4200', + }), + res, + jasmine.createSpy('next'), + ); + await mock.ended; + + expect(mock.statusCode).toBe(200); + }); + + it('accepts same-origin HTTP/2 requests using the ":authority" header', async () => { + const [res, mock] = createResponse(); + middleware( + createRequest('/__ng_rebuild', 'POST', { + ':authority': 'localhost:4200', + origin: 'https://localhost:4200', + }), + res, + jasmine.createSpy('next'), + ); + await mock.ended; + + expect(mock.statusCode).toBe(200); + }); +}); diff --git a/packages/angular/build/src/utils/manual-rebuild.ts b/packages/angular/build/src/utils/manual-rebuild.ts new file mode 100644 index 000000000000..12423b5db3d7 --- /dev/null +++ b/packages/angular/build/src/utils/manual-rebuild.ts @@ -0,0 +1,208 @@ +/** + * @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 { setTimeout as delay } from 'node:timers/promises'; +import { ChangedFiles } from './watcher'; + +/** + * The outcome of a manually requested rebuild. + * - `success`: a rebuild was performed and completed without errors. + * - `failure`: a rebuild was performed and completed with errors. + * - `no-changes`: no file changes were pending so no rebuild was performed. + * - `cancelled`: the build was stopped before the request could be fulfilled. + */ +export type ManualRebuildStatus = 'success' | 'failure' | 'no-changes' | 'cancelled'; + +export interface ManualRebuildResult { + status: ManualRebuildStatus; +} + +/** + * The default amount of time, in milliseconds, that file changes must be quiet before + * a requested rebuild starts. This allows file system events for edits completed right + * before the request to be received and coalesced by the file watcher. + */ +const DEFAULT_SETTLE_TIME = 300; + +/** + * Controls when rebuilds are performed while in watch mode. + * + * When provided to the build action, file changes detected by the watcher are accumulated + * but do not trigger a rebuild. Instead, a single incremental rebuild containing all + * accumulated changes is performed whenever {@link requestRebuild} is called. + */ +export class ManualRebuildController { + readonly #requests: ((result: ManualRebuildResult) => void)[] = []; + #listener: (() => void) | undefined; + #closed = false; + + /** + * Requests a rebuild containing all file changes detected since the previous rebuild. + * @returns A promise that resolves once the requested rebuild has completed. + */ + requestRebuild(): Promise { + if (this.#closed) { + return Promise.resolve({ status: 'cancelled' }); + } + + return new Promise((resolve) => { + this.#requests.push(resolve); + this.#listener?.(); + }); + } + + /** Whether there are rebuild requests waiting to be processed. */ + get hasPendingRequests(): boolean { + return this.#requests.length > 0; + } + + /** @internal Registers a listener that is called whenever a rebuild is requested. */ + onRequest(listener: (() => void) | undefined): void { + this.#listener = listener; + } + + /** + * @internal Removes and returns all currently pending requests. Requests made after this call + * will be fulfilled by a subsequent rebuild. + */ + takeRequests(): ((result: ManualRebuildResult) => void)[] { + return this.#requests.splice(0); + } + + /** @internal Cancels all pending requests and rejects any future requests. */ + close(): void { + this.#closed = true; + this.#listener = undefined; + for (const resolve of this.takeRequests()) { + resolve({ status: 'cancelled' }); + } + } +} + +/** + * Merges a set of changes into an existing set of accumulated changes while keeping the + * accumulated result consistent (e.g., a file that was added and later removed is only + * reported as removed). + */ +export function mergeChangedFiles(target: ChangedFiles, source: ChangedFiles): void { + for (const file of source.added) { + if (target.removed.delete(file)) { + // Removed and then re-created; treat as a modification of the original file. + target.modified.add(file); + } else if (!target.modified.has(file)) { + target.added.add(file); + } + } + + for (const file of source.modified) { + if (!target.added.has(file)) { + target.modified.add(file); + } + } + + for (const file of source.removed) { + target.added.delete(file); + target.modified.delete(file); + target.removed.add(file); + } +} + +export interface ManualRebuild { + changes: ChangedFiles; + requests: ((result: ManualRebuildResult) => void)[]; +} + +/** + * Accumulates file changes from a watcher and yields them only when a rebuild has been + * requested via the provided controller. Requests made while no changes are pending are + * resolved immediately with a `no-changes` status. + * + * @param watcher An async iterable of file changes (typically a `BuildWatcher`). + * @param controller The controller used to request rebuilds. + * @param options Additional options. + */ +export async function* waitForManualRebuilds( + watcher: AsyncIterable, + controller: ManualRebuildController, + options: { + settleTime?: number; + onChangesPending?: (changes: ChangedFiles) => void; + } = {}, +): AsyncIterable { + const settleTime = options.settleTime ?? DEFAULT_SETTLE_TIME; + + let pending = new ChangedFiles(); + let lastChangeTime = 0; + let watcherDone = false; + + // A simple signal used to wake up the main loop on new requests or watcher completion. + let wake: (() => void) | undefined; + const notify = () => { + const resolve = wake; + wake = undefined; + resolve?.(); + }; + + controller.onRequest(notify); + + // Continuously accumulate changes in the background. This completes once the watcher is closed. + void (async () => { + try { + for await (const changes of watcher) { + const hadPending = pending.all.length > 0; + mergeChangedFiles(pending, changes); + lastChangeTime = Date.now(); + if (!hadPending && pending.all.length > 0) { + options.onChangesPending?.(pending); + } + } + } catch { + // Watcher errors end the rebuild loop; the owner of the watcher handles cleanup. + } finally { + watcherDone = true; + notify(); + } + })(); + + try { + while (!watcherDone) { + if (!controller.hasPendingRequests) { + await new Promise((resolve) => (wake = resolve)); + continue; + } + + // Wait until the file watcher has been quiet for the settle time to ensure that + // edits made right before the request are included in the rebuild. + let quietFor = 0; + do { + await delay(settleTime - quietFor); + quietFor = Date.now() - lastChangeTime; + } while (!watcherDone && quietFor < settleTime); + + if (watcherDone) { + break; + } + + const requests = controller.takeRequests(); + if (pending.all.length === 0) { + for (const resolve of requests) { + resolve({ status: 'no-changes' }); + } + continue; + } + + const changes = pending; + pending = new ChangedFiles(); + + yield { changes, requests }; + } + } finally { + // The watcher itself is closed by its owner which also completes the background accumulation. + controller.close(); + } +} diff --git a/packages/angular/build/src/utils/manual-rebuild_spec.ts b/packages/angular/build/src/utils/manual-rebuild_spec.ts new file mode 100644 index 000000000000..928c69974a95 --- /dev/null +++ b/packages/angular/build/src/utils/manual-rebuild_spec.ts @@ -0,0 +1,177 @@ +/** + * @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 { + ManualRebuild, + ManualRebuildController, + mergeChangedFiles, + waitForManualRebuilds, +} from './manual-rebuild'; +import { ChangedFiles } from './watcher'; + +function createChanges(changes: Partial>) { + const result = new ChangedFiles(); + changes.added?.forEach((file) => result.added.add(file)); + changes.modified?.forEach((file) => result.modified.add(file)); + changes.removed?.forEach((file) => result.removed.add(file)); + + return result; +} + +/** A minimal controllable async iterable of file changes. */ +class FakeWatcher implements AsyncIterableIterator { + #queue: ChangedFiles[] = []; + #waiting: ((result: IteratorResult) => void) | undefined; + #closed = false; + + [Symbol.asyncIterator]() { + return this; + } + + emit(changes: ChangedFiles): void { + if (this.#waiting) { + const resolve = this.#waiting; + this.#waiting = undefined; + resolve({ value: changes }); + } else { + this.#queue.push(changes); + } + } + + close(): void { + this.#closed = true; + this.#waiting?.({ done: true, value: undefined }); + this.#waiting = undefined; + } + + next(): Promise> { + const value = this.#queue.shift(); + if (value) { + return Promise.resolve({ value }); + } + if (this.#closed) { + return Promise.resolve({ done: true, value: undefined }); + } + + return new Promise((resolve) => (this.#waiting = resolve)); + } +} + +function tick(ms = 0): Promise { + return new Promise((resolve) => setTimeout(resolve, ms)); +} + +describe('mergeChangedFiles', () => { + it('combines distinct changes', () => { + const target = createChanges({ added: ['a'] }); + mergeChangedFiles(target, createChanges({ modified: ['b'], removed: ['c'] })); + + expect([...target.added]).toEqual(['a']); + expect([...target.modified]).toEqual(['b']); + expect([...target.removed]).toEqual(['c']); + }); + + it('reports a file that was added and then removed only as removed', () => { + const target = createChanges({ added: ['a'] }); + mergeChangedFiles(target, createChanges({ removed: ['a'] })); + + expect(target.added.size).toBe(0); + expect([...target.removed]).toEqual(['a']); + }); + + it('reports a file that was removed and then added as modified', () => { + const target = createChanges({ removed: ['a'] }); + mergeChangedFiles(target, createChanges({ added: ['a'] })); + + expect(target.removed.size).toBe(0); + expect(target.added.size).toBe(0); + expect([...target.modified]).toEqual(['a']); + }); + + it('keeps a file that was added and then modified as added', () => { + const target = createChanges({ added: ['a'] }); + mergeChangedFiles(target, createChanges({ modified: ['a'] })); + + expect([...target.added]).toEqual(['a']); + expect(target.modified.size).toBe(0); + }); +}); + +describe('waitForManualRebuilds', () => { + let watcher: FakeWatcher; + let controller: ManualRebuildController; + let iterator: AsyncIterator; + + beforeEach(() => { + watcher = new FakeWatcher(); + controller = new ManualRebuildController(); + iterator = waitForManualRebuilds(watcher, controller, { settleTime: 10 })[ + Symbol.asyncIterator + ](); + }); + + afterEach(async () => { + watcher.close(); + await iterator.return?.(); + }); + + it('does not yield changes until a rebuild is requested', async () => { + let yielded = false; + const next = iterator.next().then((result) => { + yielded = true; + + return result; + }); + + watcher.emit(createChanges({ modified: ['a'] })); + watcher.emit(createChanges({ modified: ['b'] })); + await tick(50); + expect(yielded).toBeFalse(); + + const request = controller.requestRebuild(); + const { value } = await next; + + expect([...(value as ManualRebuild).changes.modified]).toEqual(['a', 'b']); + expect((value as ManualRebuild).requests.length).toBe(1); + + // Requests are resolved by the consumer once the rebuild completes + (value as ManualRebuild).requests.forEach((resolve) => resolve({ status: 'success' })); + await expectAsync(request).toBeResolvedTo({ status: 'success' }); + }); + + it('resolves requests with no-changes when there are no pending changes', async () => { + void iterator.next(); + await expectAsync(controller.requestRebuild()).toBeResolvedTo({ status: 'no-changes' }); + }); + + it('includes changes that arrive shortly after a request', async () => { + const next = iterator.next(); + + const request = controller.requestRebuild(); + watcher.emit(createChanges({ added: ['late'] })); + + const { value } = await next; + expect([...(value as ManualRebuild).changes.added]).toEqual(['late']); + (value as ManualRebuild).requests.forEach((resolve) => resolve({ status: 'success' })); + await expectAsync(request).toBeResolvedTo({ status: 'success' }); + }); + + it('cancels pending requests when the watcher closes', async () => { + const next = iterator.next(); + watcher.emit(createChanges({ modified: ['a'] })); + await tick(); + + // Close before the settle time elapses + const request = controller.requestRebuild(); + watcher.close(); + + await expectAsync(next).toBeResolvedTo({ done: true, value: undefined }); + await expectAsync(request).toBeResolvedTo({ status: 'cancelled' }); + await expectAsync(controller.requestRebuild()).toBeResolvedTo({ status: 'cancelled' }); + }); +}); diff --git a/packages/angular/cli/src/commands/mcp/devserver.ts b/packages/angular/cli/src/commands/mcp/devserver.ts index 6cf310bc6945..fb819e3b8600 100644 --- a/packages/angular/cli/src/commands/mcp/devserver.ts +++ b/packages/angular/cli/src/commands/mcp/devserver.ts @@ -27,6 +27,16 @@ const BUILD_END_MESSAGES = [ export type BuildStatus = 'success' | 'failure' | 'unknown'; +/** + * The outcome of a manually requested rebuild, as reported by the development server. + */ +export type RebuildStatus = 'success' | 'failure' | 'no-changes' | 'cancelled'; + +/** + * The development server route used to request a rebuild when manual rebuild mode is enabled. + */ +export const REBUILD_ROUTE = '/__ng_rebuild'; + /** * An Angular development server managed by the MCP server. */ @@ -58,11 +68,24 @@ export interface Devserver { */ isBuilding(): boolean; + /** + * Requests an incremental rebuild of all pending file changes. Only supported when the + * dev server was started in manual rebuild mode. + * + * Resolves once the rebuild has completed. + */ + requestRebuild(): Promise; + /** * `ng serve` port to use. */ port: number; + /** + * Whether the dev server only rebuilds when explicitly requested. + */ + manualRebuild: boolean; + /** * The workspace path for this server. */ @@ -82,6 +105,7 @@ export class LocalDevserver implements Devserver { readonly port: number; readonly workspacePath: string; readonly project: string; + readonly manualRebuild: boolean; private devserverProcess: ChildProcess | null = null; private serverLogs: string[] = []; @@ -94,16 +118,19 @@ export class LocalDevserver implements Devserver { port, workspacePath, project, + manualRebuild = false, }: { host: Host; port: number; workspacePath: string; project: string; + manualRebuild?: boolean; }) { this.host = host; this.port = port; this.workspacePath = workspacePath; this.project = project; + this.manualRebuild = manualRebuild; } start() { @@ -118,6 +145,10 @@ export class LocalDevserver implements Devserver { args.push(`--port=${this.port}`); + if (this.manualRebuild) { + args.push('--manual-rebuild'); + } + this.devserverProcess = this.host.startNgProcess(args, { stdio: 'pipe', cwd: this.workspacePath, @@ -161,7 +192,35 @@ export class LocalDevserver implements Devserver { } isBuilding() { - return this.buildInProgress; + // A stopped or crashed server is never building. + return !!this.devserverProcess && this.buildInProgress; + } + + async requestRebuild(): Promise { + if (!this.manualRebuild) { + throw new Error( + `Development server for project '${this.project}' was not started in manual rebuild mode.`, + ); + } + if (!this.devserverProcess) { + throw new Error(`Development server for project '${this.project}' is not running.`); + } + + const response = await fetch(new URL(REBUILD_ROUTE, `http://localhost:${this.port}`), { + method: 'POST', + }); + let body: { status?: RebuildStatus } | undefined; + try { + body = (await response.json()) as { status?: RebuildStatus }; + } catch {} + + if (!body?.status) { + throw new Error( + `Unexpected rebuild response from the development server (HTTP ${response.status}).`, + ); + } + + return body.status; } } diff --git a/packages/angular/cli/src/commands/mcp/mcp-server.ts b/packages/angular/cli/src/commands/mcp/mcp-server.ts index 0103e17522f3..c8d320ad7198 100644 --- a/packages/angular/cli/src/commands/mcp/mcp-server.ts +++ b/packages/angular/cli/src/commands/mcp/mcp-server.ts @@ -16,6 +16,7 @@ import { LocalWorkspaceHost, createRootRestrictedHost } from './host'; import { registerInstructionsResource } from './resources/instructions'; import { AI_TUTOR_TOOL } from './tools/ai-tutor'; import { BEST_PRACTICES_TOOL } from './tools/best-practices'; +import { DEVSERVER_REBUILD_TOOL } from './tools/devserver/devserver-rebuild'; import { DEVSERVER_START_TOOL } from './tools/devserver/devserver-start'; import { DEVSERVER_STOP_TOOL } from './tools/devserver/devserver-stop'; import { DEVSERVER_WAIT_FOR_BUILD_TOOL } from './tools/devserver/devserver-wait-for-build'; @@ -28,7 +29,12 @@ import { type AnyMcpToolDeclaration, registerTools } from './tools/tool-registry /** * Tools to manage devservers. Should be bundled together, then added to experimental or stable as a group. */ -const DEVSERVER_TOOLS = [DEVSERVER_START_TOOL, DEVSERVER_STOP_TOOL, DEVSERVER_WAIT_FOR_BUILD_TOOL]; +const DEVSERVER_TOOLS = [ + DEVSERVER_START_TOOL, + DEVSERVER_STOP_TOOL, + DEVSERVER_WAIT_FOR_BUILD_TOOL, + DEVSERVER_REBUILD_TOOL, +]; /** * The set of tools that are enabled by default for the MCP server. diff --git a/packages/angular/cli/src/commands/mcp/tools/devserver/devserver-rebuild.ts b/packages/angular/cli/src/commands/mcp/tools/devserver/devserver-rebuild.ts new file mode 100644 index 000000000000..4b0cfc8a9365 --- /dev/null +++ b/packages/angular/cli/src/commands/mcp/tools/devserver/devserver-rebuild.ts @@ -0,0 +1,120 @@ +/** + * @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'; +import { createDevServerNotFoundError, getDevserverKey } from '../../devserver'; +import { workspaceAndProjectOptions } from '../../shared-options'; +import { createStructuredContentOutput } from '../../utils'; +import { resolveWorkspaceAndProject } from '../../workspace-utils'; +import { type McpToolContext, type McpToolDeclaration, declareTool } from '../tool-registry'; + +/** + * Maximum time to wait for the build logs of a completed rebuild to be received from the + * dev server process output. + */ +const LOG_FLUSH_TIMEOUT = 2_000; // In milliseconds + +const LOG_FLUSH_INTERVAL = 50; // In milliseconds + +const devserverRebuildToolInputSchema = z.object({ + ...workspaceAndProjectOptions, +}); + +export type DevserverRebuildToolInput = z.infer; + +const devserverRebuildToolOutputSchema = z.object({ + status: z + .enum(['success', 'failure', 'no-changes', 'cancelled']) + .describe( + 'The outcome of the rebuild. "no-changes" means no file changes were pending so no rebuild was performed. ' + + '"cancelled" means the dev server stopped before the rebuild could complete.', + ), + logs: z + .array(z.string()) + .optional() + .describe('The logs from the most recent build, if a rebuild was performed.'), +}); + +export type DevserverRebuildToolOutput = z.infer; + +function wait(ms: number): Promise { + return new Promise((resolve) => setTimeout(resolve, ms)); +} + +export async function rebuildDevserver(input: DevserverRebuildToolInput, context: McpToolContext) { + const { workspacePath, projectName } = await resolveWorkspaceAndProject({ + host: context.host, + server: context.server, + workspacePathInput: input.workspace, + projectNameInput: input.project, + mcpWorkspace: context.workspace, + }); + const key = getDevserverKey(workspacePath, projectName); + const devserver = context.devservers.get(key); + + if (!devserver) { + throw createDevServerNotFoundError(context.devservers); + } + + if (!devserver.manualRebuild) { + throw new Error( + `Development server for project '${projectName}' was not started in manual rebuild mode and ` + + 'rebuilds automatically on file changes. Use "devserver_wait_for_build" instead, or restart it ' + + 'with "devserver_start" and the "manualRebuild" option.', + ); + } + + const status = await devserver.requestRebuild(); + if (status !== 'success' && status !== 'failure') { + return createStructuredContentOutput({ status, logs: undefined }); + } + + // The rebuild has completed but its log output may still be in transit from the process. + const deadline = Date.now() + LOG_FLUSH_TIMEOUT; + while (devserver.isBuilding() && Date.now() < deadline) { + await wait(LOG_FLUSH_INTERVAL); + } + + return createStructuredContentOutput({ + status, + logs: devserver.getMostRecentBuild().logs, + }); +} + +export const DEVSERVER_REBUILD_TOOL: McpToolDeclaration< + typeof devserverRebuildToolInputSchema.shape, + typeof devserverRebuildToolOutputSchema.shape +> = declareTool({ + name: 'devserver_rebuild', + title: 'Rebuild Devserver', + description: ` + +Triggers an incremental rebuild of a dev server that was started with the "devserver_start" tool in manual rebuild mode +("manualRebuild" option), waits for it to complete, and reports the build status and logs. + + +* **Applying a batch of changes:** After finishing a set of file edits (possibly across many files), call this tool once to + rebuild all of the changes together. This avoids repeated intermediate rebuilds while files are still being edited. +* **Checking a change compiles:** The returned status and logs indicate whether the rebuild succeeded and contain any + build errors to fix. + + +* This tool only works for dev servers started with "devserver_start" and "manualRebuild" set to true. Dev servers started + without it rebuild automatically; use "devserver_wait_for_build" for those instead. +* The dev server tracks file changes continuously, so only the files changed since the previous rebuild are recompiled. +* If no files changed since the previous rebuild, the tool returns the "no-changes" status without rebuilding. + +`, + isReadOnly: false, + isLocalOnly: true, + inputSchema: devserverRebuildToolInputSchema.shape, + outputSchema: devserverRebuildToolOutputSchema.shape, + factory: (context) => (input) => { + return rebuildDevserver(input, context); + }, +}); diff --git a/packages/angular/cli/src/commands/mcp/tools/devserver/devserver-start.ts b/packages/angular/cli/src/commands/mcp/tools/devserver/devserver-start.ts index 72bf5440adcb..615998a1ece7 100644 --- a/packages/angular/cli/src/commands/mcp/tools/devserver/devserver-start.ts +++ b/packages/angular/cli/src/commands/mcp/tools/devserver/devserver-start.ts @@ -22,6 +22,13 @@ const devserverStartToolInputSchema = z.object({ 'The port number to run the server on. If not provided, a random available port will be chosen. ' + 'It is recommended to reuse port numbers across calls within the same workspace to maintain consistency.', ), + manualRebuild: z + .boolean() + .optional() + .describe( + 'When true, the server tracks file changes but only rebuilds when the "devserver_rebuild" tool is called. ' + + 'Recommended when making many file edits in a batch, to avoid repeated rebuilds while files are still being edited.', + ), }); export type DevserverStartToolInput = z.infer; @@ -78,13 +85,17 @@ export async function startDevserver(input: DevserverStartToolInput, context: Mc project: projectName, port, workspacePath, + manualRebuild: input.manualRebuild, }); devserver.start(); context.devservers.set(key, devserver); return createStructuredContentOutput({ - message: `Development server for project '${projectName}' started and watching for workspace changes.`, + message: input.manualRebuild + ? `Development server for project '${projectName}' started in manual rebuild mode. ` + + `Call "devserver_rebuild" to rebuild after making changes.` + : `Development server for project '${projectName}' started and watching for workspace changes.`, address: localhostAddress(port), }); } @@ -117,6 +128,8 @@ the first build completes. changes or run more tests, as it saves time on restarts and maintains the file watcher state. You must still call 'devserver_wait_for_build' after every change to see whether the change was successfully built and be sure that the app was updated. * **Consistent Ports**: If making multiple calls, it is recommended to reuse the port you got from the first call for subsequent ones. +* **Manual Rebuilds**: Set "manualRebuild" to true to only rebuild when "devserver_rebuild" is called. This is useful when editing + many files in a batch. In this mode, call "devserver_rebuild" (instead of "devserver_wait_for_build") once all edits are done. `, isReadOnly: false, diff --git a/packages/angular/cli/src/commands/mcp/tools/devserver/devserver_spec.ts b/packages/angular/cli/src/commands/mcp/tools/devserver/devserver_spec.ts index ddefccd54633..8b4dd5e7fb88 100644 --- a/packages/angular/cli/src/commands/mcp/tools/devserver/devserver_spec.ts +++ b/packages/angular/cli/src/commands/mcp/tools/devserver/devserver_spec.ts @@ -14,6 +14,7 @@ import { addProjectToWorkspace, createMockContext, } from '../../testing/test-utils'; +import { rebuildDevserver } from './devserver-rebuild'; import { startDevserver } from './devserver-start'; import { stopDevserver } from './devserver-stop'; import { WATCH_DELAY, waitForDevserverBuild } from './devserver-wait-for-build'; @@ -174,6 +175,16 @@ describe('Serve Tools', () => { expect(stopResult.structuredContent.logs).toEqual(['Fatal error.']); }); + it('should not wait for a build if the server crashed while building', async () => { + await startDevserver({}, mockContext); + + mockProcess.stdout.emit('data', '❯ Changes detected. Rebuilding...\n'); + mockProcess.emit('close', 1); + + const waitResult = await waitForDevserverBuild({ timeout: 10 }, mockContext); + expect(waitResult.structuredContent.status).not.toBe('timeout'); + }); + it('wait should timeout if build takes too long', async () => { addProjectToWorkspace(mockContext.workspace.projects, 'timeout-app'); await startDevserver({ project: 'timeout-app' }, mockContext); @@ -236,4 +247,61 @@ describe('Serve Tools', () => { expect((e as Error).message).toContain("- Project 'app-one' in workspace path '/test'"); } }); + + describe('manual rebuild', () => { + let fetchSpy: jasmine.Spy; + + beforeEach(() => { + fetchSpy = spyOn(globalThis, 'fetch'); + }); + + it('should start the dev server in manual rebuild mode', async () => { + const startResult = await startDevserver({ manualRebuild: true }, mockContext); + expect(startResult.structuredContent.message).toContain('started in manual rebuild mode'); + expect(mockHost.startNgProcess).toHaveBeenCalledWith( + ['serve', 'my-app', '--port=12345', '--manual-rebuild'], + { stdio: 'pipe', cwd: '/test' }, + ); + }); + + it('should request a rebuild and report the build logs', async () => { + await startDevserver({ manualRebuild: true }, mockContext); + fetchSpy.and.callFake(async () => { + mockProcess.stdout.emit('data', '❯ Changes detected. Rebuilding...\n'); + mockProcess.stdout.emit('data', 'Application bundle generation complete.\n'); + + return Response.json({ status: 'success' }); + }); + + const result = await rebuildDevserver({}, mockContext); + + expect(fetchSpy).toHaveBeenCalledWith(new URL('http://localhost:12345/__ng_rebuild'), { + method: 'POST', + }); + expect(result.structuredContent.status).toBe('success'); + expect(result.structuredContent.logs).toEqual([ + '❯ Changes detected. Rebuilding...', + 'Application bundle generation complete.', + ]); + }); + + it('should report when there are no changes to rebuild', async () => { + await startDevserver({ manualRebuild: true }, mockContext); + fetchSpy.and.resolveTo(Response.json({ status: 'no-changes' })); + + const result = await rebuildDevserver({}, mockContext); + + expect(result.structuredContent.status).toBe('no-changes'); + expect(result.structuredContent.logs).toBeUndefined(); + }); + + it('should fail if the dev server is not in manual rebuild mode', async () => { + await startDevserver({}, mockContext); + + await expectAsync(rebuildDevserver({}, mockContext)).toBeRejectedWithError( + /not started in manual rebuild mode/, + ); + expect(fetchSpy).not.toHaveBeenCalled(); + }); + }); });