fix(docs-infra): convert hard-coded cli-builder examples into a proper mini-app (#34362)

Previously, the examples in the `cli-builder` guide were hard-coded.
This made it impossible to test them and verify they are correct.

This commit fixes this by converting them into a proper mini-app. In a
subsequent commit, tests will be added to verify that the source code
works as expected (and guard against regressions).

Fixes #34314

PR Close #34362

aio/content/examples/cli-builder/src/my-builder.spec.ts

@@ -0,0 +1,48 @@
+// #docregion
+import { Architect } from '@angular-devkit/architect';
+import { TestingArchitectHost } from '@angular-devkit/architect/testing';
+import { logging, schema } from '@angular-devkit/core';
+
+describe('Command Runner Builder', () => {
+  let architect: Architect;
+  let architectHost: TestingArchitectHost;
+
+  beforeEach(async () => {
+    const registry = new schema.CoreSchemaRegistry();
+    registry.addPostTransform(schema.transforms.addUndefinedDefaults);
+
+    // TestingArchitectHost() takes workspace and current directories.
+    // Since we don't use those, both are the same in this case.
+    architectHost = new TestingArchitectHost(__dirname, __dirname);
+    architect = new Architect(architectHost, registry);
+
+    // This will either take a Node package name, or a path to the directory
+    // for the package.json file.
+    await architectHost.addBuilderFromPackage('..');
+  });
+
+  it('can run node', async () => {
+    // Create a logger that keeps an array of all messages that were logged.
+    const logger = new logging.Logger('');
+    const logs = [];
+    logger.subscribe(ev => logs.push(ev.message));
+
+    // A "run" can have multiple outputs, and contains progress information.
+    const run = await architect.scheduleBuilder('@example/command-runner:command', {
+      command: 'node',
+      args: ['--print', '\'foo\''],
+    }, { logger });  // We pass the logger for checking later.
+
+    // The "result" member (of type BuilderOutput) is the next output.
+    const output = await run.result;
+
+    // Stop the builder from running. This stops Architect from keeping
+    // the builder-associated states in memory, since builders keep waiting
+    // to be scheduled.
+    await run.stop();
+
+    // Expect that foo was logged
+    expect(logs).toContain('foo');
+  });
+});
+// #enddocregion

aio/content/examples/cli-builder/src/my-builder.ts

@@ -0,0 +1,46 @@
+// #docplaster
+// #docregion builder, builder-skeleton, handling-output, progress-reporting
+import { BuilderContext, BuilderOutput, createBuilder } from '@angular-devkit/architect';
+import { JsonObject } from '@angular-devkit/core';
+// #enddocregion builder-skeleton
+import * as childProcess from 'child_process';
+// #docregion builder-skeleton
+
+interface Options extends JsonObject {
+  command: string;
+  args: string[];
+}
+
+export default createBuilder(commandBuilder);
+
+function commandBuilder(
+  options: Options,
+  context: BuilderContext,
+  ): Promise<BuilderOutput> {
+    // #enddocregion builder, builder-skeleton, handling-output
+    // #docregion report-status
+    context.reportStatus(`Executing "${options.command}"...`);
+    // #docregion builder, handling-output
+    const child = childProcess.spawn(options.command, options.args);
+    // #enddocregion builder, report-status
+
+    child.stdout.on('data', data => {
+      context.logger.info(data.toString());
+    });
+    child.stderr.on('data', data => {
+      context.logger.error(data.toString());
+    });
+
+    // #docregion builder
+    return new Promise(resolve => {
+      // #enddocregion builder, handling-output
+      context.reportStatus(`Done.`);
+      // #docregion builder, handling-output
+      child.on('close', code => {
+        resolve({ success: code === 0 });
+      });
+    });
+    // #docregion builder-skeleton
+}
+
+// #enddocregion builder, builder-skeleton, handling-output, progress-reporting