feat(@angular/cli): add ng completion init

`ng completion init` sets up Angular CLI autocompletion for the current user by appending `source <(ng completion)` to their `~/.bashrc`, `~/.bash_profile`, `~/.zshrc`, `~/.zsh_profile`, or `~/.profile`.

I couldn't find a good way of testing an error when writing to the `~/.bashrc` file. Since the CLI checks if it has access to the file first, that would usually fail in any circumstance when the file can't be written to. Things could change in between (user modifies file permissions or disk runs out of storage), but there's no easy hook to simulate this change in the e2e test.

Refs #23003.

Author: dgp1130

packages/angular/cli/src/commands/completion/cli.ts

@@ -8,18 +8,57 @@
 
 import { join } from 'path';
 import yargs, { Argv } from 'yargs';
-import { CommandModule, CommandModuleImplementation } from '../../command-builder/command-module';
+import {
+  CommandModule,
+  CommandModuleImplementation,
+  CommandScope,
+} from '../../command-builder/command-module';
+import { addCommandModuleToYargs } from '../../command-builder/utilities/command';
+import { colors } from '../../utilities/color';
+import { initializeAutocomplete } from '../../utilities/completion';
 
 export class CompletionCommandModule extends CommandModule implements CommandModuleImplementation {
   command = 'completion';
   describe = 'Generate a bash and zsh real-time type-ahead autocompletion script.';
   longDescriptionPath = join(__dirname, 'long-description.md');
 
   builder(localYargs: Argv): Argv {
-    return localYargs;
+    return addCommandModuleToYargs(localYargs, CompletionInitCommandModule, this.context);
   }
 
   run(): void {
     yargs.showCompletionScript();
   }
 }
+
+class CompletionInitCommandModule extends CommandModule implements CommandModuleImplementation {
+  command = 'init';
+  describe = 'Set up Angular CLI autocompletion for your terminal.';
+  longDescriptionPath = undefined;
+  static override scope = CommandScope.Both;
+
+  builder(localYargs: Argv): Argv {
+    return localYargs;
+  }
+
+  async run(): Promise<number> {
+    let rcFile: string;
+    try {
+      rcFile = await initializeAutocomplete();
+    } catch (err) {
+      this.context.logger.error(err.message);
+
+      return 1;
+    }
+
+    this.context.logger.info(
+      `
+Appended \`source <(ng completion)\` to \`${rcFile}\`. Restart your terminal or run the following to autocomplete \`ng commands\`:
+
+    ${colors.yellow('source <(ng completion)')}
+      `.trim(),
+    );
+
+    return 0;
+  }
+}

packages/angular/cli/src/commands/completion/long-description.md

@@ -1 +1,5 @@
-To enable bash and zsh real-time type-ahead autocompletion, copy and paste the generated script to your `.bashrc`, `.bash_profile`, `.zshrc` or `.zsh_profile`.
+To enable Bash and Zsh real-time type-ahead autocompletion, run
+`ng completion init` and restart your terminal.
+
+Alternatively, append `source <(ng completion)` to the appropriate `.bashrc`,
+`.bash_profile`, `.zshrc`, `.zsh_profile`, or `.profile` file.

packages/angular/cli/src/utilities/completion.ts

@@ -0,0 +1,75 @@
+/**
+ * @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.io/license
+ */
+
+import { promises as fs } from 'fs';
+import * as path from 'path';
+import { env } from 'process';
+
+/**
+ * Sets up autocompletion for the user's terminal. This attempts to find the configuration file for
+ * the current shell (`.bashrc`, `.zshrc`, etc.) and append a command which enables autocompletion
+ * for the Angular CLI. Supports only Bash and Zsh. Returns whether or not it was successful.
+ * @return The full path of the configuration file modified.
+ */
+export async function initializeAutocomplete(): Promise<string> {
+  // Get the currently active `$SHELL` and `$HOME` environment variables.
+  const shell = env['SHELL'];
+  if (!shell) {
+    throw new Error(
+      '`$SHELL` environment variable not set. Angular CLI autocompletion only supports Bash or' +
+        ' Zsh.',
+    );
+  }
+  const home = env['HOME'];
+  if (!home) {
+    throw new Error(
+      '`$HOME` environment variable not set. Setting up autocompletion modifies configuration files' +
+        ' in the home directory and must be set.',
+    );
+  }
+
+  // Get all the files we can add `ng completion` to which apply to the user's `$SHELL`.
+  const runCommandCandidates = getShellRunCommandCandidates(shell, home);
+  if (!runCommandCandidates) {
+    throw new Error(
+      `Unknown \`$SHELL\` environment variable value (${shell}). Angular CLI autocompletion only supports Bash or Zsh.`,
+    );
+  }
+
+  // Get the first file that already exists or fallback to a new file of the first candidate.
+  const candidates = await Promise.allSettled(
+    runCommandCandidates.map((rcFile) => fs.access(rcFile).then(() => rcFile)),
+  );
+  const rcFile =
+    candidates.find(
+      (result): result is PromiseFulfilledResult<string> => result.status === 'fulfilled',
+    )?.value ?? runCommandCandidates[0];
+
+  // Append Angular autocompletion setup to RC file.
+  try {
+    await fs.appendFile(
+      rcFile,
+      '\n\n# Load Angular CLI autocompletion.\nsource <(ng completion)\n',
+    );
+  } catch (err) {
+    throw new Error(`Failed to append autocompletion setup to \`${rcFile}\`:\n${err.message}`);
+  }
+
+  return rcFile;
+}
+
+/** Returns an ordered list of possibile candidates of RC files used by the given shell. */
+function getShellRunCommandCandidates(shell: string, home: string): string[] | undefined {
+  if (shell.toLowerCase().includes('bash')) {
+    return ['.bashrc', '.bash_profile', '.profile'].map((file) => path.join(home, file));
+  } else if (shell.toLowerCase().includes('zsh')) {
+    return ['.zshrc', '.zsh_profile', '.profile'].map((file) => path.join(home, file));
+  } else {
+    return undefined;
+  }
+}