feat(cli): add generator to build CLI command index from ebook markdown; prefer generated index in show/search; add tests and docs (#435)

Author: RajdeepKushwaha5

cli/README.md

@@ -58,6 +58,21 @@ Here are some examples of how to use the CLI:
     linux-cli show ls
     ```
 
+## Generating the CLI command index
+
+The CLI can consume a generated index of commands parsed from the ebook markdown. This keeps the CLI registry in sync with the eBook source.
+
+To generate or refresh the index, run the generator from the `cli/` directory:
+
+```powershell
+# from the repo root
+cd cli
+python scripts/generate_command_index.py
+```
+
+That will create `cli/data/commands.json` which `show` and `search` will prefer when present. The test `tests/test_generate_index.py` exercises the generator.
+
+
 ## Development
 
 ### Running Tests

cli/cli.py

@@ -21,15 +21,16 @@ def resolve_command(self, ctx: click.Context, args: List[str]):
 
             if "No such command" in original:
                 script_name = ctx.find_root().info_name or "cli"
-                hint = f"💡 Hint: Run '{script_name} --help' to see available commands."
+                # Keep hint ASCII-only to avoid UnicodeEncodeError on some consoles
+                hint = f"Hint: Run '{script_name} --help' to see available commands."
 
                 new_message = f"{original}\n{hint}"
                 raise click.exceptions.UsageError(new_message, ctx=ctx) from e
 
             raise
 
 
-app = typer.Typer(help="101 Linux Commands CLI 🚀", cls=CustomTyper)
+app = typer.Typer(help="101 Linux Commands CLI", cls=CustomTyper)
 app.add_typer(hello.app, name="hello")
 app.add_typer(list.app, name="list")
 app.add_typer(version.app, name="version")
@@ -40,7 +41,7 @@ def resolve_command(self, ctx: click.Context, args: List[str]):
 
 # Main callback to handle global options
 def main_callback(
-    verbose: bool = typer.Option(False, "--verbose", help="Enable verbose output")
+    verbose: bool = typer.Option(False, "--verbose", help="Enable verbose output"),
 ) -> None:
     verbose_flag["enabled"] = verbose
     if verbose:

cli/commands/search.py

@@ -1,19 +1,36 @@
 from typing import Dict, List
 
+import json
+from pathlib import Path
 import typer
 
 from states.global_state import debug, verbose_flag
 
-app = typer.Typer(
-    help=("Search available commands by keyword " "(name or description).")
-)
+
+app = typer.Typer(help=("Search available commands by keyword (name or description)."))
 
 
 def _get_available_commands() -> List[Dict[str, str]]:
     """
-    Mocked list of available commands.
-    Replace with real registry/source when available.
+    Return commands loaded from cli/data/commands.json if available, else fall back
+    to the mocked in-code list.
     """
+    data_path = Path(__file__).parent.parent / "data" / "commands.json"
+    if data_path.exists():
+        try:
+            data = json.loads(data_path.read_text(encoding="utf-8"))
+            # normalize to list of dicts with name/description
+            return [
+                {
+                    "name": item.get("name", ""),
+                    "description": item.get("description", ""),
+                }
+                for item in data
+            ]
+        except Exception:
+            pass
+
+    # fallback mocked data
     return [
         {"name": "ls", "description": "List directory contents"},
         {"name": "grep", "description": "Search for PATTERN in files"},
@@ -27,13 +44,13 @@ def _get_available_commands() -> List[Dict[str, str]]:
         },
         {
             "name": "cat",
-            "description": ("Concatenate files and print on the standard " "output"),
+            "description": ("Concatenate files and print on the standard output"),
         },
         {"name": "head", "description": "Output the first part of files"},
         {"name": "tail", "description": "Output the last part of files"},
         {
             "name": "sed",
-            "description": ("Stream editor for filtering and transforming " "text"),
+            "description": ("Stream editor for filtering and transforming text"),
         },
     ]
 

cli/commands/show.py

@@ -1,5 +1,7 @@
 from typing import Dict, TypedDict
 
+import json
+from pathlib import Path
 import typer
 
 from states.global_state import debug, verbose_flag
@@ -12,63 +14,95 @@ class CommandInfo(TypedDict):
     notes: str
 
 
-COMMANDS: Dict[str, CommandInfo] = {
-    "ls": {
-        "description": (
-            "List information about the files in the current directory (the default). "
-            "Options can be used to modify the output format, sort order, and more."
-        ),
-        "usage": "ls [OPTION]... [FILE]...",
-        "example": "ls -la /var/log",
-        "notes": (
-            "- `-l` : use a long listing format\n"
-            "- `-a` : show hidden files (starting with `.`)\n"
-            "- `-h` : with -l, print sizes in human-readable format (e.g., 1K, 234M)"
-        ),
-    },
-    "grep": {
-        "description": (
-            "Search input files for lines containing a match to the given PATTERN. "
-            "Often used for filtering log files or searching through code."
-        ),
-        "usage": "grep [OPTION]... PATTERN [FILE]...",
-        "example": 'grep -R "TODO" .',
-        "notes": (
-            "- `-i` : ignore case distinctions\n"
-            "- `-R` : recursively search subdirectories\n"
-            "- `-n` : show line numbers of matches"
-        ),
-    },
-    "cat": {
-        "description": (
-            "Concatenate files and print on the standard output. "
-            "Often used to quickly view file contents."
-        ),
-        "usage": "cat [OPTION]... [FILE]...",
-        "example": "cat /etc/passwd",
-        "notes": (
-            "- `-n` : number all output lines\n"
-            "- `-b` : number non-blank lines\n"
-            "- Use with pipes: `cat file.txt | grep pattern`"
-        ),
-    },
-    "mkdir": {
-        "description": (
-            "Create directories if they do not already exist. "
-            "By default, it creates a single directory."
-        ),
-        "usage": "mkdir [OPTION]... DIRECTORY...",
-        "example": "mkdir -p projects/python/app",
-        "notes": (
-            "- `-p` : create parent directories as needed\n"
-            "- `-v` : print a message for each created directory"
-        ),
-    },
-}
+def _load_commands_from_json() -> Dict[str, CommandInfo] | None:
+    data_path = Path(__file__).parent.parent / "data" / "commands.json"
+    if not data_path.exists():
+        return None
+    try:
+        data = json.loads(data_path.read_text(encoding="utf-8"))
+        result: Dict[str, CommandInfo] = {}
+        for item in data:
+            key = item.get("name")
+            if not key:
+                continue
+            result[key] = {
+                "description": item.get("description", ""),
+                "usage": item.get("usage", ""),
+                "example": item.get("example", ""),
+                "notes": item.get("notes", ""),
+            }
+        return result
+    except Exception:
+        return None
+
+
+# Try to load a generated commands index, otherwise fall back to the baked-in dataset
+_LOADED_COMMANDS = _load_commands_from_json()
+
+
+COMMANDS: Dict[str, CommandInfo]
+
+if _LOADED_COMMANDS is not None:
+    COMMANDS = _LOADED_COMMANDS
+else:
+    # fallback in-code registry
+    COMMANDS = {
+        "ls": {
+            "description": (
+                "List information about the files in the current directory (the default). "
+                "Options can be used to modify the output format, sort order, and more."
+            ),
+            "usage": "ls [OPTION]... [FILE]...",
+            "example": "ls -la /var/log",
+            "notes": (
+                "- `-l` : use a long listing format\n"
+                "- `-a` : show hidden files (starting with `.`)\n"
+                "- `-h` : with -l, print sizes in human-readable format (e.g., 1K, 234M)"
+            ),
+        },
+        "grep": {
+            "description": (
+                "Search input files for lines containing a match to the given PATTERN. "
+                "Often used for filtering log files or searching through code."
+            ),
+            "usage": "grep [OPTION]... PATTERN [FILE]...",
+            "example": 'grep -R "TODO" .',
+            "notes": (
+                "- `-i` : ignore case distinctions\n"
+                "- `-R` : recursively search subdirectories\n"
+                "- `-n` : show line numbers of matches"
+            ),
+        },
+        "cat": {
+            "description": (
+                "Concatenate files and print on the standard output. "
+                "Often used to quickly view file contents."
+            ),
+            "usage": "cat [OPTION]... [FILE]...",
+            "example": "cat /etc/passwd",
+            "notes": (
+                "- `-n` : number all output lines\n"
+                "- `-b` : number non-blank lines\n"
+                "- Use with pipes: `cat file.txt | grep pattern`"
+            ),
+        },
+        "mkdir": {
+            "description": (
+                "Create directories if they do not already exist. "
+                "By default, it creates a single directory."
+            ),
+            "usage": "mkdir [OPTION]... DIRECTORY...",
+            "example": "mkdir -p projects/python/app",
+            "notes": (
+                "- `-p` : create parent directories as needed\n"
+                "- `-v` : print a message for each created directory"
+            ),
+        },
+    }
 
 
 def show(
-    command: str = typer.Argument(..., help="Linux command to show details for")
+    command: str = typer.Argument(..., help="Linux command to show details for"),
 ) -> None:
     """
     Display description, usage, examples, and notes for a given Linux command.
@@ -79,7 +113,7 @@ def show(
 
     if not info:
         typer.secho(
-            f"✖ Unknown command '{command}'. Try one of: {', '.join(sorted(COMMANDS))}",
+            f"Unknown command '{command}'. Try one of: {', '.join(sorted(COMMANDS))}",
             err=True,
             fg=typer.colors.RED,
         )

cli/commands/version.py

@@ -5,11 +5,12 @@
 
 import typer
 
+# Ensure parent package path is available before importing package-level metadata
+sys.path.insert(0, str(Path(__file__).parent.parent))
+
 from __version__ import __version__
 from states.global_state import debug, verbose_flag
 
-sys.path.insert(0, str(Path(__file__).parent.parent))
-
 app = typer.Typer(help="version command")