Feat init profile

apps/sparo-lib/assets/sparo-profile.json

@@ -0,0 +1,46 @@
+{
+  "$schema": "https://tiktok.github.io/sparo/schemas/sparo-profile.schema.json",
+
+  /**
+   * A list of Rush project selectors indicating the project folders to be
+   * included for sparse checkout.  The selectors will be combined to make
+   * the union superset of projects.  See the Rush selector docs for details:
+   * https://rushjs.io/pages/developer/selecting_subsets/
+   */
+  "selections": [
+    /**
+     * For example, include all Rush projects tagged with "tag:my-team"
+     * as well as the dependency workspace projects needed to build them.
+     */
+    // {
+    //   "selector": "--to",
+    //   "argument": "tag:my-team"
+    // },
+    /**
+     * For example, include the project called "my-library", as well as all
+     * projects that are impacted by changes to it, as well as the dependency
+     * projects needed to build everything.
+     */
+    // {
+    //   "selector": "--from",
+    //   "argument": "my-library"
+    // }
+  ],
+
+  /**
+   * A list of arbitrary additional folders to be included, not necessarily
+   * corresponding to any workspace project.
+   */
+  "includeFolders": [
+    // "path/to/include"
+  ],
+
+  /**
+   * A list of folders to be excluded.  This field takes precedence over
+   * the "includeFolders" and "selections" fields, guaranteeing that the
+   * specified path will definitely not be included.
+   */
+  "excludeFolders": [
+    // "path/to/exclude"
+  ]
+}

apps/sparo-lib/src/cli/commands/cmd-list.ts

@@ -12,11 +12,15 @@ import { GitCloneCommand } from './git-clone';
 import { GitCheckoutCommand } from './git-checkout';
 import { GitFetchCommand } from './git-fetch';
 import { GitPullCommand } from './git-pull';
+import { InitProfileCommand } from './init-profile';
 
+// When adding new Sparo subcommands, remember to update this doc page:
+// https://github.com/tiktok/sparo/blob/main/apps/website/docs/pages/commands/overview.md
 export const COMMAND_LIST: Constructable[] = [
   HelpCommand,
-  ListProfilesCommand,
   AutoConfigCommand,
+  ListProfilesCommand,
+  InitProfileCommand,
 
   CloneCommand,
   CheckoutCommand,

apps/sparo-lib/src/cli/commands/init-profile.ts

@@ -0,0 +1,70 @@
+import { FileSystem } from '@rushstack/node-core-library';
+import type { Argv, ArgumentsCamelCase } from 'yargs';
+
+import { Command } from '../../decorator';
+import { TerminalService } from '../../services/TerminalService';
+import { ICommand } from './base';
+import { SparoProfileService } from '../../services/SparoProfileService';
+import { inject } from 'inversify';
+import { assetsFolderPath } from './util';
+import { Colorize } from '@rushstack/terminal';
+
+export interface IInitProjectCommandOptions {
+  profile: string;
+}
+
+@Command()
+export class InitProfileCommand implements ICommand<IInitProjectCommandOptions> {
+  public cmd: string = 'init-profile';
+  public description: string = 'Initialize a new profile.';
+
+  // template section name --> whether it should be commented out
+  private _commentedBySectionName: Map<string, boolean> = new Map<string, boolean>();
+
+  @inject(SparoProfileService) private _sparoProfileService!: SparoProfileService;
+  @inject(TerminalService) private _terminalService!: TerminalService;
+
+  public builder(yargs: Argv<IInitProjectCommandOptions>): void {
+    yargs.string('profile').demandOption(['profile']);
+  }
+
+  public handler = async (
+    args: ArgumentsCamelCase<IInitProjectCommandOptions>,
+    terminalService: TerminalService
+  ): Promise<void> => {
+    const { profile } = args;
+
+    const destinationPath: string = this._sparoProfileService.getProfileFilepathByName(profile);
+
+    if (this._sparoProfileService.hasProfileInFS(profile)) {
+      throw new Error(
+        `Error: A config file already exists for the profile name "${profile}":\n  ` + destinationPath
+      );
+    }
+
+    const sparoProfileTemplateFilepath: string = `${assetsFolderPath}/sparo-profile.json`;
+
+    if (!FileSystem.exists(sparoProfileTemplateFilepath)) {
+      // THIS SHOULD NEVER HAPPEN
+      throw new Error(`Unable to find sparo profile template file at ${sparoProfileTemplateFilepath}`);
+    }
+
+    await FileSystem.copyFileAsync({
+      sourcePath: sparoProfileTemplateFilepath,
+      destinationPath
+    });
+    this._terminalService.terminal.writeLine(
+      Colorize.green(`Successfully initialized the "${profile}" profile.`)
+    );
+    this._terminalService.terminal.writeLine();
+    this._terminalService.terminal.writeLine(
+      'Next step: Open this file in your editor and configure the project selectors:'
+    );
+    this._terminalService.terminal.writeLine();
+    this._terminalService.terminal.writeLine('  ' + Colorize.cyan(destinationPath));
+  };
+
+  public getHelp(): string {
+    return 'init-profile help';
+  }
+}

apps/sparo-lib/src/cli/commands/util.ts

@@ -1,3 +1,15 @@
+import { PackageJsonLookup } from '@rushstack/node-core-library';
+
+/**
+ * The currently-executing sparo-lib package's root folder path.
+ */
+export const sparoLibFolderRootPath: string = PackageJsonLookup.instance.tryGetPackageFolderFor(__dirname)!;
+
+/**
+ * The path to the assets folder in rush-lib.
+ */
+export const assetsFolderPath: string = `${sparoLibFolderRootPath}/assets`;
+
 /**
  * The string of cmd here can be "clone <repository> [directory]", this function extracts
  *  the command name from the string.

apps/sparo-lib/src/services/SparoProfileService.ts

@@ -75,10 +75,22 @@ export class SparoProfileService {
 
   private get _sparoProfileFolder(): string {
     const repoRoot: string = this._gitService.getRepoInfo().root;
+    if (!repoRoot) {
+      throw new Error(`Failed to detect git repository. Please check running in a git repository folder.`);
+    }
     const sparoProfileFolder: string = path.resolve(repoRoot, defaultSparoProfileFolder);
     return sparoProfileFolder;
   }
 
+  /**
+   * Returns the absolute file path where the specified profile name would be stored.
+   * @remarks
+   * It is not guaranteed that the file actually exists.
+   */
+  public getProfileFilepathByName(profileName: string): string {
+    return path.resolve(this._sparoProfileFolder, `${profileName}.json`);
+  }
+
   private static _getProfileName(profilePath: string): string {
     const pathArr: string[] = profilePath.split('/');
     const last: string = pathArr[pathArr.length - 1];

apps/website/docs/pages/commands/overview.md

@@ -23,6 +23,7 @@ Sparo has four kinds of subcommands:
 4. **Auxiliary subcommands** are new subcommands that provide Sparo-specific functionality.  They are:
   - `sparo purge`
   - `sparo list-profiles`
+  - `sparo init-profile`
 
 ## Mirrored commands
 

common/changes/sparo/feat-init-profile_2024-02-23-19-26.json

@@ -0,0 +1,10 @@
+{
+  "changes": [
+    {
+      "packageName": "sparo",
+      "comment": "Add \"sparo init-profile --profile <name>\" command",
+      "type": "none"
+    }
+  ],
+  "packageName": "sparo"
+}