elspais 0.11.1__py3-none-any.whl → 0.43.5__py3-none-any.whl

elspais/cli.py

@@ -10,7 +10,21 @@ from pathlib import Path
 from typing import List, Optional
 
 from elspais import __version__
-from elspais.commands import analyze, changed, config_cmd, edit, hash_cmd, index, init, rules_cmd, trace, validate, reformat_cmd
+from elspais.commands import (
+    analyze,
+    changed,
+    config_cmd,
+    edit,
+    example_cmd,
+    hash_cmd,
+    health,
+    index,
+    init,
+    reformat_cmd,
+    rules_cmd,
+    trace,
+    validate,
+)
 
 
 def create_parser() -> argparse.ArgumentParser:
@@ -28,8 +42,17 @@ Examples:
   elspais hash update           # Update all requirement hashes
   elspais changed               # Show uncommitted spec changes
   elspais analyze hierarchy     # Show requirement hierarchy tree
-  elspais config show           # View current configuration
-  elspais init                  # Create .elspais.toml configuration
+
+Configuration:
+  elspais init                  # Create .elspais.toml in current directory
+  elspais config path           # Show config file location
+  elspais config show           # View all settings
+  elspais config --help         # Configuration guide with examples
+
+Documentation:
+  elspais example               # Quick requirement format reference
+  elspais example --full        # Full specification document
+  elspais completion            # Shell tab-completion setup
 
 For detailed command help: elspais <command> --help
         """,
@@ -54,12 +77,14 @@ For detailed command help: elspais <command> --help
         metavar="PATH",
     )
     parser.add_argument(
-        "-v", "--verbose",
+        "-v",
+        "--verbose",
         action="store_true",
         help="Verbose output",
     )
     parser.add_argument(
-        "-q", "--quiet",
+        "-q",
+        "--quiet",
         action="store_true",
         help="Suppress non-error output",
     )
@@ -90,13 +115,12 @@ Common rules to skip:
     validate_parser.add_argument(
         "--fix",
         action="store_true",
-        help="Auto-fix fixable issues",
+        help="Auto-fix issues that can be corrected programmatically (hashes, status)",
     )
     validate_parser.add_argument(
-        "--core-repo",
-        type=Path,
-        help="Path to core repository (for associated repo validation)",
-        metavar="PATH",
+        "--dry-run",
+        action="store_true",
+        help="Show what would be fixed without making changes (use with --fix)",
     )
     validate_parser.add_argument(
         "--skip-rule",
@@ -105,25 +129,64 @@ Common rules to skip:
         metavar="RULE",
     )
     validate_parser.add_argument(
-        "-j", "--json",
+        "-j",
+        "--json",
         action="store_true",
         help="Output requirements as JSON (hht_diary compatible format)",
     )
-    validate_parser.add_argument(
-        "--tests",
+    # NOTE: --tests, --no-tests, --mode removed (dead code - never implemented)
+
+    # health command
+    health_parser = subparsers.add_parser(
+        "health",
+        help="Check repository and configuration health",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog="""
+Examples:
+  elspais health              # Run all health checks
+  elspais health --config     # Check config only
+  elspais health --spec       # Check spec files only
+  elspais health --code       # Check code references only
+  elspais health --tests      # Check test mappings only
+  elspais health -j           # Output JSON for tooling
+  elspais health -v           # Verbose output with details
+
+Checks performed:
+  CONFIG: TOML syntax, required fields, pattern tokens, hierarchy rules, paths
+  SPEC:   File parsing, duplicate IDs, reference resolution, orphans
+  CODE:   Code→REQ reference validation, coverage statistics
+  TESTS:  Test→REQ mappings, result status, coverage statistics
+""",
+    )
+    health_parser.add_argument(
+        "--config",
+        dest="config_only",
         action="store_true",
-        help="Force test scanning even if disabled in config",
+        help="Run configuration checks only",
     )
-    validate_parser.add_argument(
-        "--no-tests",
+    health_parser.add_argument(
+        "--spec",
+        dest="spec_only",
         action="store_true",
-        help="Skip test scanning",
+        help="Run spec file checks only",
     )
-    validate_parser.add_argument(
-        "--mode",
-        choices=["core", "combined"],
-        default="combined",
-        help="Scope: core (this repo only), combined (include sponsor repos)",
+    health_parser.add_argument(
+        "--code",
+        dest="code_only",
+        action="store_true",
+        help="Run code reference checks only",
+    )
+    health_parser.add_argument(
+        "--tests",
+        dest="tests_only",
+        action="store_true",
+        help="Run test mapping checks only",
+    )
+    health_parser.add_argument(
+        "-j",
+        "--json",
+        action="store_true",
+        help="Output as JSON",
     )
 
     # trace command
@@ -169,23 +232,19 @@ Common rules to skip:
         action="store_true",
         help="Start review server (requires trace-review extra)",
     )
+    # NOTE: --port, --mode, --sponsor, --graph removed (dead code - never implemented)
+    # Graph-based trace options
     trace_parser.add_argument(
-        "--port",
-        type=int,
-        default=8080,
-        help="Port for review server (default: 8080)",
-    )
-    trace_parser.add_argument(
-        "--mode",
-        choices=["core", "sponsor", "combined"],
-        default="core",
-        help="Report mode: core, sponsor, or combined (default: core)",
+        "--graph-json",
+        action="store_true",
+        help="Output graph structure as JSON",
     )
     trace_parser.add_argument(
-        "--sponsor",
-        help="Sponsor name for sponsor-specific reports",
-        metavar="NAME",
+        "--report",
+        choices=["minimal", "standard", "full"],
+        help="Report preset to use (default: standard)",
     )
+    # NOTE: --depth removed (dead code - never implemented)
 
     # hash command
     hash_parser = subparsers.add_parser(
@@ -262,12 +321,14 @@ Common rules to skip:
         metavar="BRANCH",
     )
     changed_parser.add_argument(
-        "-j", "--json",
+        "-j",
+        "--json",
         action="store_true",
         help="Output as JSON",
     )
     changed_parser.add_argument(
-        "-a", "--all",
+        "-a",
+        "--all",
         action="store_true",
         help="Include all changed files (not just spec)",
     )
@@ -303,6 +364,38 @@ Common rules to skip:
         action="store_true",
         help="Overwrite existing configuration",
     )
+    init_parser.add_argument(
+        "--template",
+        action="store_true",
+        help="Create an example requirement file in spec/",
+    )
+
+    # example command
+    example_parser = subparsers.add_parser(
+        "example",
+        help="Display requirement format examples and templates",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog="""
+Subcommands:
+  elspais example             Quick reference (default)
+  elspais example requirement Full requirement template with all sections
+  elspais example journey     User journey template
+  elspais example assertion   Assertion rules and examples
+  elspais example ids         Show ID patterns from current config
+  elspais example --full      Display spec/requirements-spec.md (if exists)
+""",
+    )
+    example_parser.add_argument(
+        "example_type",
+        nargs="?",
+        choices=["requirement", "journey", "assertion", "ids"],
+        help="Example type to display",
+    )
+    example_parser.add_argument(
+        "--full",
+        action="store_true",
+        help="Display the full requirements specification file",
+    )
 
     # edit command
     edit_parser = subparsers.add_parser(
@@ -317,7 +410,7 @@ Examples:
   elspais edit --from-json edits.json
 
 JSON batch format:
-  {"edits": [{"req_id": "...", "status": "...", "implements": [...]}]}
+  [{"req_id": "...", "status": "...", "implements": [...]}]
 """,
     )
     edit_parser.add_argument(
@@ -360,6 +453,39 @@ JSON batch format:
     config_parser = subparsers.add_parser(
         "config",
         help="View and modify configuration (show, get, set, ...)",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog="""
+Configuration File:
+  elspais looks for .elspais.toml in the current directory or parent directories.
+  Create one with: elspais init
+
+  Location: elspais config path
+  View all: elspais config show
+
+Quick Start (.elspais.toml):
+  [project]
+  name = "my-project"
+  spec_dir = "spec"              # Where requirement files live
+
+  [patterns]
+  prefix = "REQ"                 # Requirement ID prefix
+  separator = "-"                # ID separator (REQ-p00001)
+
+  [rules]
+  strict_mode = false            # Strict implements semantics
+
+  [rules.hierarchy]
+  allowed = ["dev -> ops, prd", "ops -> prd"]
+
+Common Commands:
+  elspais config show            # View current config
+  elspais config get patterns.prefix
+  elspais config set project.name "MyApp"
+  elspais config path            # Show config file location
+
+Full Documentation:
+  See docs/configuration.md for all options.
+""",
     )
     config_subparsers = config_parser.add_subparsers(dest="config_action")
 
@@ -374,7 +500,8 @@ JSON batch format:
         metavar="SECTION",
     )
     config_show.add_argument(
-        "-j", "--json",
+        "-j",
+        "--json",
         action="store_true",
         help="Output as JSON",
     )
@@ -389,7 +516,8 @@ JSON batch format:
         help="Configuration key (dot-notation, e.g., 'patterns.prefix')",
     )
     config_get.add_argument(
-        "-j", "--json",
+        "-j",
+        "--json",
         action="store_true",
         help="Output as JSON",
     )
@@ -405,7 +533,7 @@ JSON batch format:
     )
     config_set.add_argument(
         "value",
-        help="Value to set (type auto-detected: true/false, numbers, JSON arrays/objects, or string)",
+        help="Value to set (auto-detected: bool, number, JSON array/object, string)",
     )
 
     # config unset
@@ -475,51 +603,105 @@ JSON batch format:
         help="Content rule file name (e.g., 'AI-AGENT.md')",
     )
 
-    # reformat-with-claude command
-    reformat_parser = subparsers.add_parser(
+    # reformat-with-claude command (NOT YET IMPLEMENTED - placeholder for future feature)
+    subparsers.add_parser(
         "reformat-with-claude",
-        help="Reformat requirements using AI (Acceptance Criteria -> Assertions)",
+        help="[NOT IMPLEMENTED] Reformat requirements using AI (Acceptance Criteria -> Assertions)",
     )
-    reformat_parser.add_argument(
-        "--start-req",
-        help="Starting requirement ID (default: all PRD requirements)",
-        metavar="ID",
-    )
-    reformat_parser.add_argument(
-        "--depth",
-        type=int,
-        help="Maximum traversal depth (default: unlimited)",
-    )
-    reformat_parser.add_argument(
-        "--dry-run",
-        action="store_true",
-        help="Preview changes without applying",
-    )
-    reformat_parser.add_argument(
-        "--backup",
-        action="store_true",
-        help="Create .bak files before editing",
+    # NOTE: All arguments removed - command not yet implemented
+    # See src/elspais/commands/reformat_cmd.py for planned features
+
+    # docs command - comprehensive user documentation
+    docs_parser = subparsers.add_parser(
+        "docs",
+        help="Read the user guide (topics: quickstart, format, hierarchy, ...)",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog="""
+Available Topics:
+  quickstart   Getting started with elspais (default)
+  format       Requirement file format and structure
+  hierarchy    PRD → OPS → DEV levels and implements
+  assertions   Writing testable assertions with SHALL
+  traceability Linking requirements to code and tests
+  validation   Running validation and fixing issues
+  git          Change detection and git integration
+  config       Configuration file reference
+  mcp          MCP server for AI integration
+  all          Show complete documentation
+
+Examples:
+  elspais docs                  # Quick start guide
+  elspais docs format           # Requirement format reference
+  elspais docs all              # Complete documentation
+  elspais docs all --no-pager   # Disable pager
+""",
     )
-    reformat_parser.add_argument(
-        "--force",
+    docs_parser.add_argument(
+        "topic",
+        nargs="?",
+        default="quickstart",
+        choices=[
+            "quickstart",
+            "format",
+            "hierarchy",
+            "assertions",
+            "traceability",
+            "validation",
+            "git",
+            "config",
+            "commands",
+            "health",
+            "mcp",
+            "all",
+        ],
+        help="Documentation topic (default: quickstart)",
+    )
+    docs_parser.add_argument(
+        "--plain",
         action="store_true",
-        help="Reformat even if already in new format",
+        help="Plain text output (no ANSI colors)",
     )
-    reformat_parser.add_argument(
-        "--fix-line-breaks",
+    docs_parser.add_argument(
+        "--no-pager",
         action="store_true",
-        help="Normalize line breaks (remove extra blank lines)",
+        help="Disable paging (print directly to stdout)",
     )
-    reformat_parser.add_argument(
-        "--line-breaks-only",
-        action="store_true",
-        help="Only fix line breaks, skip AI-based reformatting",
+
+    # completion command - shell tab-completion setup
+    completion_parser = subparsers.add_parser(
+        "completion",
+        help="Generate shell tab-completion scripts",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog="""
+Shell Completion Setup:
+
+  First, install the completion extra:
+    pip install elspais[completion]
+
+  Bash (add to ~/.bashrc):
+    eval "$(register-python-argcomplete elspais)"
+
+  Zsh (add to ~/.zshrc):
+    autoload -U bashcompinit
+    bashcompinit
+    eval "$(register-python-argcomplete elspais)"
+
+  Fish (add to ~/.config/fish/config.fish):
+    register-python-argcomplete --shell fish elspais | source
+
+  Tcsh (add to ~/.tcshrc):
+    eval `register-python-argcomplete --shell tcsh elspais`
+
+  Global activation (for all argcomplete-enabled tools):
+    activate-global-python-argcomplete
+
+After adding the appropriate line, restart your shell or source the config file.
+""",
     )
-    reformat_parser.add_argument(
-        "--mode",
-        choices=["combined", "core-only", "local-only"],
-        default="combined",
-        help="Which repos to include in hierarchy (default: combined)",
+    completion_parser.add_argument(
+        "--shell",
+        choices=["bash", "zsh", "fish", "tcsh"],
+        help="Generate script for specific shell",
     )
 
     # mcp command
@@ -587,6 +769,17 @@ def main(argv: Optional[List[str]] = None) -> int:
         Exit code (0 for success, non-zero for failure)
     """
     parser = create_parser()
+
+    # Enable shell tab-completion if argcomplete is installed
+    # Install with: pip install elspais[completion]
+    # Then activate: eval "$(register-python-argcomplete elspais)"
+    try:
+        import argcomplete
+
+        argcomplete.autocomplete(parser)
+    except ImportError:
+        pass
+
     args = parser.parse_args(argv)
 
     # Handle no command
@@ -594,10 +787,28 @@ def main(argv: Optional[List[str]] = None) -> int:
         parser.print_help()
         return 0
 
+    # Auto-detect git repository root and change to it
+    # This ensures elspais works the same from any subdirectory
+    import os
+
+    from elspais.config import find_git_root
+
+    original_cwd = Path.cwd()
+    git_root = find_git_root(original_cwd)
+
+    if git_root and git_root != original_cwd:
+        os.chdir(git_root)
+        if args.verbose:
+            print(f"Working from repository root: {git_root}", file=sys.stderr)
+    elif not git_root and args.verbose:
+        print("Warning: Not in a git repository", file=sys.stderr)
+
     try:
         # Dispatch to command handlers
         if args.command == "validate":
             return validate.run(args)
+        elif args.command == "health":
+            return health.run(args)
         elif args.command == "trace":
             return trace.run(args)
         elif args.command == "hash":
@@ -612,6 +823,8 @@ def main(argv: Optional[List[str]] = None) -> int:
             return version_command(args)
         elif args.command == "init":
             return init.run(args)
+        elif args.command == "example":
+            return example_cmd.run(args)
         elif args.command == "edit":
             return edit.run(args)
         elif args.command == "config":
@@ -620,6 +833,10 @@ def main(argv: Optional[List[str]] = None) -> int:
             return rules_cmd.run(args)
         elif args.command == "reformat-with-claude":
             return reformat_cmd.run(args)
+        elif args.command == "docs":
+            return docs_command(args)
+        elif args.command == "completion":
+            return completion_command(args)
         elif args.command == "mcp":
             return mcp_command(args)
         else:
@@ -636,6 +853,105 @@ def main(argv: Optional[List[str]] = None) -> int:
         return 1
 
 
+def docs_command(args: argparse.Namespace) -> int:
+    """Handle docs command - display user documentation from markdown files."""
+    import pydoc
+
+    from elspais.utilities.docs_loader import load_all_topics, load_topic
+    from elspais.utilities.md_renderer import render_markdown
+
+    topic = args.topic
+    use_pager = not args.no_pager and sys.stdout.isatty()
+    use_color = not args.plain and sys.stdout.isatty()
+
+    # Load content from markdown files
+    if topic == "all":
+        content = load_all_topics()
+    else:
+        content = load_topic(topic)
+
+    if content is None:
+        print(f"Error: Documentation not found for topic '{topic}'", file=sys.stderr)
+        print("Documentation files may not be installed correctly.", file=sys.stderr)
+        return 1
+
+    # Render markdown to ANSI and display
+    output = render_markdown(content, use_color=use_color)
+
+    if use_pager:
+        pydoc.pager(output)
+    else:
+        print(output)
+
+    return 0
+
+
+def completion_command(args: argparse.Namespace) -> int:
+    """Handle completion command - generate shell completion scripts."""
+    import importlib.util
+
+    if importlib.util.find_spec("argcomplete") is None:
+        print("Error: argcomplete not installed.", file=sys.stderr)
+        print("Install with: pip install elspais[completion]", file=sys.stderr)
+        return 1
+
+    shell = args.shell
+
+    if shell:
+        # Generate script for specific shell
+        import subprocess
+
+        shell_flag = f"--shell={shell}" if shell in ("fish", "tcsh") else ""
+        cmd = ["register-python-argcomplete"]
+        if shell_flag:
+            cmd.append(shell_flag)
+        cmd.append("elspais")
+
+        try:
+            result = subprocess.run(cmd, capture_output=True, text=True)
+            if result.returncode == 0:
+                print(result.stdout)
+            else:
+                print(f"Error generating completion script: {result.stderr}", file=sys.stderr)
+                return 1
+        except FileNotFoundError:
+            print("Error: register-python-argcomplete not found.", file=sys.stderr)
+            print("Make sure argcomplete is properly installed.", file=sys.stderr)
+            return 1
+    else:
+        # Show setup instructions
+        print(
+            """
+Shell Completion Setup for elspais
+===================================
+
+Bash (add to ~/.bashrc):
+  eval "$(register-python-argcomplete elspais)"
+
+Zsh (add to ~/.zshrc):
+  autoload -U bashcompinit
+  bashcompinit
+  eval "$(register-python-argcomplete elspais)"
+
+Fish (add to ~/.config/fish/config.fish):
+  register-python-argcomplete --shell fish elspais | source
+
+Tcsh (add to ~/.tcshrc):
+  eval `register-python-argcomplete --shell tcsh elspais`
+
+Generate script for a specific shell:
+  elspais completion --shell bash
+  elspais completion --shell zsh
+  elspais completion --shell fish
+  elspais completion --shell tcsh
+
+After adding the line, restart your shell or source the config file.
+"""
+        )
+
+    return 0
+
+
 def version_command(args: argparse.Namespace) -> int:
     """Handle version command."""
     print(f"elspais {__version__}")
@@ -662,7 +978,7 @@ def mcp_command(args: argparse.Namespace) -> int:
         if hasattr(args, "spec_dir") and args.spec_dir:
             working_dir = args.spec_dir.parent
 
-        print(f"Starting elspais MCP server...")
+        print("Starting elspais MCP server...")
         print(f"Working directory: {working_dir}")
         print(f"Transport: {args.transport}")
 

elspais/commands/__init__.py

@@ -3,10 +3,16 @@ elspais.commands - CLI command implementations
 """
 
 __all__ = [
-    "validate",
-    "trace",
+    "analyze",
+    "changed",
+    "config_cmd",
+    "edit",
+    "example_cmd",
     "hash_cmd",
     "index",
-    "analyze",
     "init",
+    "reformat_cmd",
+    "rules_cmd",
+    "trace",
+    "validate",
 ]