feat: add Amplify CLI command reference (aws-amplify#4950)

* feat: add Amplify CLI command reference

* chore: migrate next.config, directory to ESM. enables reading cli command info from npm distribution

* chore: add amplify-cli-core as a dependency

* fix: inline code block sidenav link

* migrate away from 'tasks' cmd, mjs tasks

* jest to transform mjs

* directory import to use mjs extension, correct expected error message

* revert error message correction due to different node versions

* update lockfile

* fix subcommand descriptions, remove usage subsections

* pin amplify-cli-core version

* add types, fix usage of table captions

* patch duplicate subcommands from dataset

* update lockfile from main

* use scoped package, update to 4+

Author: josefaidt

next.config.js renamed to next.config.mjs

@@ -1,3 +1,12 @@
+import { createRequire } from 'node:module';
+import dotenv from 'dotenv';
+import _withMDX from '@next/mdx';
+import { directory } from './src/directory/directory.mjs';
+const require = createRequire(import.meta.url);
+
+dotenv.config({ path: './.env.custom' });
+
+// eslint-disable-next-line @typescript-eslint/no-var-requires
 const withTM = require('next-transpile-modules')([
   '@algolia/autocomplete-shared'
 ]); // pass the modules you would like to see transpiled
@@ -7,12 +16,7 @@ const mdxRenderer = `
 
 `;
 
-// eslint-disable-next-line @typescript-eslint/no-var-requires
-const directory = require('./src/directory/directory.js');
-
-require('dotenv').config({ path: './.env.custom' });
-
-module.exports = async (phase, { defaultConfig }) => {
+export default async (phase, { defaultConfig }) => {
   // eslint-disable-next-line @typescript-eslint/no-var-requires
   const headingLinkPlugin = await require('./src/plugins/headings.tsx');
   // eslint-disable-next-line @typescript-eslint/no-var-requires
@@ -26,7 +30,7 @@ module.exports = async (phase, { defaultConfig }) => {
   // eslint-disable-next-line @typescript-eslint/no-var-requires
   const frontmatterPlugin = await require('./src/plugins/frontmatter.tsx');
 
-  const withMDX = require('@next/mdx')({
+  const withMDX = _withMDX({
     extension: /\.mdx$/,
     options: {
       remarkPlugins: [

package.json

@@ -18,6 +18,7 @@
     "@algolia/autocomplete-shared": "^1.5.6",
     "@algolia/autocomplete-theme-classic": "^1.6.1",
     "@algolia/client-search": "^4.13.0",
+    "@aws-amplify/amplify-cli-core": "^4.0.1",
     "@aws-amplify/ui-components": "latest",
     "@aws-amplify/ui-react": "^4.4.3",
     "@emotion/react": "^11.1.5",
@@ -98,11 +99,12 @@
     "decode-uri-component": "0.2.1"
   },
   "jest": {
+    "preset": "ts-jest",
     "roots": [
       "<rootDir>/src"
     ],
     "transform": {
-      "^.+\\.(ts|tsx|js)$": [
+      "^.+\\.(ts|tsx|js|mjs)$": [
         "babel-jest",
         {
           "presets": [
@@ -123,12 +125,11 @@
   "scripts": {
     "clean": "rm -rf node_modules yarn.lock",
     "refresh": "yarn clean && yarn",
-    "task": "ts-node tasks",
     "test": "jest",
     "dev": "next dev",
     "spellcheck": "cspell \"src/**/*.mdx\"",
     "spellcheck-diff": "git diff --name-only --cached | awk \"/src.*\\.mdx/{print}\" | npx cspell --no-must-find-files --file-list stdin",
-    "build": "yarn task generate-sitemap && next build && next export -o client/www/next-build",
+    "build": "node tasks/generate-sitemap.mjs && next build && next export -o client/www/next-build",
     "next-build": "next build",
     "next-start": "next start",
     "amplify:submissionsLambda": "cd amplify/backend/function/submissionsLambda/src && yarn install && yarn build && yarn test",

src/components/Menu/Directory/__tests__/Directory.test.tsx

@@ -1,7 +1,7 @@
 import * as React from 'react';
 import { render, screen } from '@testing-library/react';
 import Directory from '../index';
-import directory from '../../../../directory/directory';
+import directory from '../../../../directory/directory.mjs';
 
 describe('Directory', () => {
   const directoryKeys = Object.keys(directory);

src/components/Menu/Directory/index.tsx

@@ -8,20 +8,7 @@ import {
   DirectoryLinksStyle,
   ProductRootLinkStyle
 } from './styles';
-
-export type DirectoryItem = {
-  /**
-   * Title used for sidenav link, page title, and page heading
-   */
-  title: string;
-  /**
-   * Control whether the title should be displayed as inline code
-   * @default false
-   */
-  isCodeTitle: boolean;
-  route: string;
-  filters: string[];
-};
+import type { DirectoryItem } from '../../../directory/directory';
 
 export type DirectoryGroupProps = {
   title: string;
@@ -100,7 +87,9 @@ class DirectoryGroup extends React.Component<
               >
                 <InternalLink href={`${item.route}`}>
                   {item.isCodeTitle ? (
-                    <code>{item.title}</code>
+                    <a>
+                      <code>{item.title}</code>
+                    </a>
                   ) : (
                     item.title
                   )}

src/components/Menu/VersionSwitcher/index.tsx

@@ -1,6 +1,6 @@
 import Link from "next/link";
 import {ActiveSwitchStyle, SwitchStyle} from "./styles";
-import directory from "../../../directory/directory";
+import directory from "../../../directory/directory.mjs";
 
 const ui = directory["ui"].items;
 const uiLegacy = directory["ui-legacy"].items;

src/components/Menu/__tests__/Menu.test.tsx

@@ -1,7 +1,7 @@
 import * as React from 'react';
 import { render, screen } from '@testing-library/react';
 import Menu from '../index';
-import directory from '../../../directory/directory';
+import directory from '../../../directory/directory.mjs';
 
 jest.mock('../RepoActions', () => () => <div>Repo Actions</div>);
 Object.defineProperty(window, 'matchMedia', {

src/data/cli-commands.d.ts

@@ -0,0 +1,14 @@
+export type CliCommandFlag = {
+  short: string;
+  long: string;
+  description: string;
+};
+
+export type CliCommand = {
+  name: string;
+  description: string;
+  usage: string;
+  learnMoreLink?: string;
+  flags: CliCommandFlag[] | [];
+  subCommands?: CliCommand[];
+};

src/data/cli-commands.mjs

@@ -0,0 +1,49 @@
+import { commandsInfo } from 'amplify-cli-core/lib/help/commands-info.js';
+
+/**
+ * Get and transform command data
+ * @returns {import('./cli-commands').CliCommand[]} Array of commands
+ */
+export function getCliCommands() {
+  const result = [];
+  for (const command of commandsInfo) {
+    const { subCommands } = command;
+    result.push({
+      name: command.command,
+      description: command.commandDescription,
+      usage: command.commandUsage,
+      flags: command.commandFlags.length
+        ? command.commandFlags.map((flag) => ({
+            short: flag.short,
+            long: flag.long,
+            description: flag.flagDescription
+          }))
+        : [],
+      subCommands: subCommands.length
+        ? subCommands
+            .map((subCommand) => ({
+              name: subCommand.subCommand,
+              description: subCommand.subCommandDescription,
+              usage: subCommand.subCommandUsage,
+              flags: subCommand.subCommandFlags.length
+                ? subCommand.subCommandFlags.map((flag) => ({
+                    short: flag.short,
+                    long: flag.long,
+                    description: flag.flagDescription
+                  }))
+                : []
+            }))
+            .reduce((acc, subCommand) => {
+              /** @todo remove this .reduce() after duplicates are removed from the data set */
+              if (!acc.find((cmd) => cmd.name === subCommand.name)) {
+                acc.push(subCommand);
+              }
+              return acc;
+            }, [])
+        : []
+    });
+  }
+  return result;
+}
+
+export const commands = getCliCommands();

src/directory/directory.d.ts

@@ -0,0 +1,29 @@
+export type DirectoryItem = {
+  /**
+   * Title used for sidenav link, page title, and page heading
+   */
+  title: string;
+  filters?: string[];
+  /**
+   * Control whether the title should be displayed as inline code
+   * @default false
+   */
+  isCodeTitle?: boolean;
+  route: string;
+};
+
+export type Directory = {
+  productRoot: {
+    title: string;
+    route: string;
+  };
+  items: Record<
+    string,
+    {
+      title: string;
+      items: DirectoryItem[];
+      route?: string;
+      filters?: string[];
+    }
+  >;
+};

src/directory/directory.js renamed to src/directory/directory.mjs

@@ -1,4 +1,9 @@
-const directory = {
+import { commands } from '../data/cli-commands.mjs';
+
+/**
+ * @type {Record<string, import('./directory').Directory>}
+ */
+export const directory = {
   contribute: {
     productRoot: {
       title: 'Contribute',
@@ -1674,6 +1679,16 @@ const directory = {
           }
         ]
       },
+      commands: {
+        title: 'Commands',
+        items: commands
+          .sort((a, b) => ((a.name > b.name ? 1 : -1)))
+          .map(({ name }) => ({
+            isCodeTitle: true,
+            title: name,
+            route: `/cli/commands/${name}`
+          }))
+      },
       graphql: {
         title: 'API (GraphQL)',
         items: [
@@ -2666,4 +2681,4 @@ const directory = {
   }
 };
 
-module.exports = directory;
+export default directory;