Architect Management

/**
 * Main class for managing builders and targets in an Angular workspace
 */
class Architect {
  /**
   * Create a new Architect instance
   * @param host - Host implementation providing workspace access
   * @param registry - Optional JSON schema registry for validation
   * @param additionalJobRegistry - Optional additional job registry
   */
  constructor(
    host: ArchitectHost,
    registry?: json.schema.SchemaRegistry,
    additionalJobRegistry?: Registry
  );
  
  /**
   * Check if a job name exists in the registry
   * @param name - Job name to check
   * @returns Observable indicating if job exists
   */
  has(name: JobName): Observable<boolean>;
  
  /**
   * Schedule a builder by name
   * @param name - Builder name in format "package:builder"
   * @param options - Options to pass to the builder
   * @param scheduleOptions - Additional scheduling options
   * @returns Promise resolving to BuilderRun instance
   */
  scheduleBuilder(
    name: string,
    options: json.JsonObject,
    scheduleOptions?: ScheduleOptions
  ): Promise<BuilderRun>;
  
  /**
   * Schedule a target from the workspace configuration
   * @param target - Target specification with project, target, and optional configuration
   * @param overrides - Options to override workspace configuration
   * @param scheduleOptions - Additional scheduling options
   * @returns Promise resolving to BuilderRun instance
   */
  scheduleTarget(
    target: Target,
    overrides?: json.JsonObject,
    scheduleOptions?: ScheduleOptions
  ): Promise<BuilderRun>;
}

import { Architect } from "@angular-devkit/architect";
import { NodeModulesArchitectHost } from "@angular-devkit/architect/node";
import { logging } from "@angular-devkit/core";

// Create architect with Node.js host
const host = new NodeModulesArchitectHost(process.cwd());
const architect = new Architect(host);

// Schedule a builder directly
const builderRun = await architect.scheduleBuilder(
  "@angular-devkit/build-angular:browser",
  { outputPath: "dist/my-app" }
);

// Schedule a target from workspace configuration  
const targetRun = await architect.scheduleTarget(
  { project: "my-app", target: "build", configuration: "production" },
  { aot: true }, // overrides
  { logger: new logging.Logger("build") } // schedule options
);

// Get build results
const result = await targetRun.result;
console.log(result.success ? "Success!" : "Failed!");

// Monitor progress
targetRun.progress.subscribe(progress => {
  console.log(`Progress: ${progress.current}/${progress.total}`);
});

// Stop execution
await targetRun.stop();

/**
 * Additional optional scheduling options
 */
interface ScheduleOptions {
  /**
   * Logger to pass to the builder. Messages will be forwarded through this logger.
   */
  logger?: logging.Logger;
  
  /**
   * Target to pass to the builder (for builders scheduled via scheduleBuilder)
   */
  target?: Target;
}

/**
 * A running builder instance returned from scheduling operations
 */
interface BuilderRun {
  /**
   * Unique identifier for this run, same as context ID
   */
  id: number;
  
  /**
   * Builder information and metadata
   */
  info: BuilderInfo;
  
  /**
   * Promise resolving to the next output from the builder
   */
  result: Promise<BuilderOutput>;
  
  /**
   * Promise resolving to the last output from the builder
   */
  lastOutput: Promise<BuilderOutput>;
  
  /**
   * Observable stream of all outputs from the builder
   */
  output: Observable<BuilderOutput>;
  
  /**
   * Observable stream of progress reports from the builder
   */
  progress: Observable<BuilderProgressReport>;
  
  /**
   * Stop the builder execution
   * @returns Promise resolving when builder is stopped
   */
  stop(): Promise<void>;
}

// Different ways to consume builder results
const run = await architect.scheduleTarget({ project: "app", target: "build" });

// Get first result (recommended for single builds)
const firstResult = await run.result;
if (firstResult.success) {
  console.log("Build completed successfully");
}

// Get final result (recommended for watch mode)
const finalResult = await run.lastOutput;

// Stream all outputs (for watch mode or multiple outputs)
run.output.subscribe(output => {
  console.log("Build output:", output);
});

// Monitor detailed progress
run.progress.subscribe(progress => {
  if (progress.state === BuilderProgressState.Running) {
    console.log(`${progress.status} - ${progress.current}/${progress.total}`);
  }
});

// Clean shutdown
process.on('SIGINT', async () => {
  await run.stop();
  process.exit(0);
});

/**
 * Host interface that Architect uses to access workspace and builder information
 */
interface ArchitectHost<BuilderInfoT extends BuilderInfo = BuilderInfo> {
  /**
   * Get the builder name for a target
   * @param target - The target to inspect
   * @returns Promise resolving to builder name or null if not found
   */
  getBuilderNameForTarget(target: Target): Promise<string | null>;
  
  /**
   * Resolve builder information by name
   * @param builderName - The name of the builder to resolve
   * @returns Promise resolving to builder info or null if not found
   */
  resolveBuilder(builderName: string): Promise<BuilderInfoT | null>;
  
  /**
   * Load a builder instance from builder info
   * @param info - Builder information to load from
   * @returns Promise resolving to builder instance or null if load failed
   */
  loadBuilder(info: BuilderInfoT): Promise<Builder | null>;
  
  /**
   * Get current working directory
   * @returns Promise resolving to current directory path
   */
  getCurrentDirectory(): Promise<string>;
  
  /**
   * Get workspace root directory
   * @returns Promise resolving to workspace root path
   */
  getWorkspaceRoot(): Promise<string>;
  
  /**
   * Get options for a target from workspace configuration
   * @param target - Target to get options for
   * @returns Promise resolving to options object or null if not found
   */
  getOptionsForTarget(target: Target): Promise<json.JsonObject | null>;
  
  /**
   * Get project metadata by project name
   * @param projectName - Name of the project
   * @returns Promise resolving to project metadata or null if not found
   */
  getProjectMetadata(projectName: string): Promise<json.JsonObject | null>;
  
  /**
   * Get project metadata by target
   * @param target - Target containing project information
   * @returns Promise resolving to project metadata or null if not found
   */
  getProjectMetadata(target: Target): Promise<json.JsonObject | null>;
}

import { NodeModulesArchitectHost } from "@angular-devkit/architect/node";

// Use built-in Node.js host
const host = new NodeModulesArchitectHost('/path/to/workspace');
const architect = new Architect(host);

// Or create custom host
class CustomHost implements ArchitectHost {
  async getBuilderNameForTarget(target: Target): Promise<string | null> {
    // Custom logic to resolve builder names
    return `@custom/builders:${target.target}`;
  }
  
  async resolveBuilder(builderName: string): Promise<BuilderInfo | null> {
    // Custom logic to resolve builder information
    return {
      builderName,
      description: "Custom builder",
      optionSchema: { type: "object" }
    };
  }
  
  // ... implement other methods
}

const customArchitect = new Architect(new CustomHost());