feat(@angular/cli): make ng completion set up CLI autocompletion by modifying .bashrc files

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

The previous `ng completion` functionality (printing Yargs autocompletion shell script) is moved to `ng completion script` because most users won't need to worry about this, so we're prioritizing `ng completion` as the part most users will actually type.

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,13 +8,51 @@
 
 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.';
+  describe = 'Set up Angular CLI autocompletion for your terminal.';
   longDescriptionPath = join(__dirname, 'long-description.md');
 
+  builder(localYargs: Argv): Argv {
+    return addCommandModuleToYargs(localYargs, CompletionScriptCommandModule, this.context);
+  }
+
+  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 script)\` to \`${rcFile}\`. Restart your terminal or run the following to autocomplete \`ng\` commands:
+
+    ${colors.yellow('source <(ng completion script)')}
+      `.trim(),
+    );
+
+    return 0;
+  }
+}
+
+class CompletionScriptCommandModule extends CommandModule implements CommandModuleImplementation {
+  command = 'script';
+  describe = 'Generate a bash and zsh real-time type-ahead autocompletion script.';
+  longDescriptionPath = undefined;
+
   builder(localYargs: Argv): Argv {
     return localYargs;
   }

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` and restart your terminal.
+
+Alternatively, append `source <(ng completion script)` 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 script)\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;
+  }
+}

tests/legacy-cli/e2e/tests/misc/completion-script.ts

@@ -0,0 +1,63 @@
+import { execAndWaitForOutputToMatch } from '../../utils/process';
+
+export default async function () {
+  // ng build
+  await execAndWaitForOutputToMatch(
+    'ng',
+    ['--get-yargs-completions', 'ng', 'b', ''],
+    /test-project/,
+  );
+  await execAndWaitForOutputToMatch(
+    'ng',
+    ['--get-yargs-completions', 'ng', 'build', ''],
+    /test-project/,
+  );
+  await execAndWaitForOutputToMatch(
+    'ng',
+    ['--get-yargs-completions', 'ng', 'build', '--a'],
+    /--aot/,
+  );
+  await execAndWaitForOutputToMatch(
+    'ng',
+    ['--get-yargs-completions', 'ng', 'build', '--configuration'],
+    /production/,
+  );
+  await execAndWaitForOutputToMatch(
+    'ng',
+    ['--get-yargs-completions', 'ng', 'b', '--configuration'],
+    /production/,
+  );
+
+  // ng run
+  await execAndWaitForOutputToMatch(
+    'ng',
+    ['--get-yargs-completions', 'ng', 'run', ''],
+    /test-project\\:build\\:development/,
+  );
+  await execAndWaitForOutputToMatch(
+    'ng',
+    ['--get-yargs-completions', 'ng', 'run', ''],
+    /test-project\\:build/,
+  );
+  await execAndWaitForOutputToMatch(
+    'ng',
+    ['--get-yargs-completions', 'ng', 'run', ''],
+    /test-project\\:test/,
+  );
+  await execAndWaitForOutputToMatch(
+    'ng',
+    ['--get-yargs-completions', 'ng', 'run', 'test-project:build'],
+    /test-project\\:build\\:development/,
+  );
+  await execAndWaitForOutputToMatch(
+    'ng',
+    ['--get-yargs-completions', 'ng', 'run', 'test-project:'],
+    /test-project\\:test/,
+  );
+  await execAndWaitForOutputToMatch(
+    'ng',
+    ['--get-yargs-completions', 'ng', 'run', 'test-project:build'],
+    // does not include 'test-project:serve'
+    /^((?!:serve).)*$/,
+  );
+}