pdd-cli 0.0.55__py3-none-any.whl → 0.0.57__py3-none-any.whl

pdd/__init__.py

@@ -1,6 +1,6 @@
 """PDD - Prompt Driven Development"""
 
-__version__ = "0.0.55"
+__version__ = "0.0.57"
 
 # Strength parameter used for LLM extraction across the codebase
 # Used in postprocessing, XML tagging, code generation, and other extraction

pdd/auto_deps_main.py

@@ -49,7 +49,8 @@ def auto_deps_main(  # pylint: disable=too-many-arguments, too-many-locals
             force=ctx.obj.get('force', False),
             quiet=ctx.obj.get('quiet', False),
             command="auto-deps",
-            command_options=command_options
+            command_options=command_options,
+            context_override=ctx.obj.get('context')
         )
 
         # Get the CSV file path
@@ -101,4 +102,4 @@ def auto_deps_main(  # pylint: disable=too-many-arguments, too-many-locals
     except Exception as exc:
         if not ctx.obj.get('quiet', False):
             rprint(f"[bold red]Error:[/bold red] {str(exc)}")
-        sys.exit(1)
+        sys.exit(1)

pdd/bug_main.py

@@ -50,7 +50,8 @@ def bug_main(
             force=ctx.obj.get('force', False),
             quiet=ctx.obj.get('quiet', False),
             command="bug",
-            command_options=command_options
+            command_options=command_options,
+            context_override=ctx.obj.get('context')
         )
         
         # Use the language detected by construct_paths if none was explicitly provided
@@ -117,4 +118,4 @@ def bug_main(
     except Exception as e:
         if not ctx.obj.get('quiet', False):
             rprint(f"[bold red]Error:[/bold red] {str(e)}")
-        sys.exit(1)
+        sys.exit(1)

pdd/change_main.py

@@ -203,6 +203,7 @@ def change_main(
                 quiet=quiet,
                 command="change",
                 command_options=command_options,
+                context_override=ctx.obj.get('context')
             )
             logger.debug("construct_paths returned:")
             logger.debug("  input_strings keys: %s", list(input_strings.keys()))

pdd/cli.py

@@ -8,6 +8,8 @@ generating code, tests, fixing issues, and managing prompts.
 from __future__ import annotations
 
 import os
+import subprocess
+import sys
 from typing import Any, Dict, List, Optional, Tuple
 from pathlib import Path # Import Path
 
@@ -26,13 +28,18 @@ from .cmd_test_main import cmd_test_main
 from .code_generator_main import code_generator_main
 from .conflicts_main import conflicts_main
 # Need to import construct_paths for tests patching pdd.cli.construct_paths
-from .construct_paths import construct_paths
+from .construct_paths import construct_paths, list_available_contexts
 from .context_generator_main import context_generator_main
 from .crash_main import crash_main
 from .detect_change_main import detect_change_main
 from .fix_main import fix_main
 from .fix_verification_main import fix_verification_main
-from .install_completion import install_completion, get_local_pdd_path
+from .install_completion import (
+    install_completion,
+    get_local_pdd_path,
+    get_current_shell,
+    get_shell_rc_path,
+)
 from .preprocess_main import preprocess_main
 from .pytest_output import run_pytest_and_capture_output
 from .split_main import split_main
@@ -40,6 +47,7 @@ from .sync_main import sync_main
 from .trace_main import trace_main
 from .track_cost import track_cost
 from .update_main import update_main
+from . import template_registry
 
 
 # --- Initialize Rich Console ---
@@ -75,8 +83,89 @@ def handle_error(exception: Exception, command_name: str, quiet: bool):
     # Do NOT re-raise e here. Let the command function return None.
 
 
+def _first_pending_command(ctx: click.Context) -> Optional[str]:
+    """Return the first subcommand scheduled for this invocation."""
+    for arg in ctx.protected_args:
+        if not arg.startswith("-"):
+            return arg
+    return None
+
+
+def _api_env_exists() -> bool:
+    """Check whether the ~/.pdd/api-env file exists."""
+    return (Path.home() / ".pdd" / "api-env").exists()
+
+
+def _completion_installed() -> bool:
+    """Check if the shell RC file already sources the PDD completion script."""
+    shell = get_current_shell()
+    rc_path = get_shell_rc_path(shell) if shell else None
+    if not rc_path:
+        return False
+
+    try:
+        content = Path(rc_path).read_text(encoding="utf-8")
+    except (OSError, UnicodeDecodeError):
+        return False
+
+    return "PDD CLI completion" in content or "pdd_completion" in content
+
+
+def _project_has_local_configuration() -> bool:
+    """Detect project-level env configuration that should suppress reminders."""
+    cwd = Path.cwd()
+
+    env_file = cwd / ".env"
+    if env_file.exists():
+        try:
+            env_content = env_file.read_text(encoding="utf-8")
+        except (OSError, UnicodeDecodeError):
+            env_content = ""
+        if any(token in env_content for token in ("OPENAI_API_KEY=", "GOOGLE_API_KEY=", "ANTHROPIC_API_KEY=")):
+            return True
+
+    project_pdd_dir = cwd / ".pdd"
+    if project_pdd_dir.exists():
+        return True
+
+    return False
+
+
+def _should_show_onboarding_reminder(ctx: click.Context) -> bool:
+    """Determine whether to display the onboarding reminder banner."""
+    suppress = os.getenv("PDD_SUPPRESS_SETUP_REMINDER", "").lower()
+    if suppress in {"1", "true", "yes"}:
+        return False
+
+    first_command = _first_pending_command(ctx)
+    if first_command == "setup":
+        return False
+
+    if _api_env_exists():
+        return False
+
+    if _project_has_local_configuration():
+        return False
+
+    if _completion_installed():
+        return False
+
+    return True
+
+
+def _run_setup_utility() -> None:
+    """Execute the interactive setup utility script."""
+    setup_script = Path(__file__).resolve().parent.parent / "utils" / "pdd-setup.py"
+    if not setup_script.exists():
+        raise FileNotFoundError(f"Setup utility not found at {setup_script}")
+
+    result = subprocess.run([sys.executable, str(setup_script)])
+    if result.returncode not in (0, None):
+        raise RuntimeError(f"Setup utility exited with status {result.returncode}")
+
+
 # --- Main CLI Group ---
-@click.group(chain=True, help="PDD (Prompt-Driven Development) Command Line Interface.")
+@click.group(invoke_without_command=True, help="PDD (Prompt-Driven Development) Command Line Interface.")
 @click.option(
     "--force",
     is_flag=True,
@@ -134,6 +223,20 @@ def handle_error(exception: Exception, command_name: str, quiet: bool):
     default=False,
     help="Run commands locally instead of in the cloud.",
 )
+@click.option(
+    "--context",
+    "context_override",
+    type=str,
+    default=None,
+    help="Override automatic context detection and use the specified .pddrc context.",
+)
+@click.option(
+    "--list-contexts",
+    "list_contexts",
+    is_flag=True,
+    default=False,
+    help="List available contexts from .pddrc and exit.",
+)
 @click.version_option(version=__version__, package_name="pdd-cli")
 @click.pass_context
 def cli(
@@ -147,10 +250,11 @@ def cli(
     review_examples: bool,
     local: bool,
     time: Optional[float], # Type hint is Optional[float]
+    context_override: Optional[str],
+    list_contexts: bool,
 ):
     """
     Main entry point for the PDD CLI. Handles global options and initializes context.
-    Supports multi-command chaining.
     """
     # Ensure PDD_PATH is set before any commands run
     get_local_pdd_path()
@@ -166,11 +270,44 @@ def cli(
     ctx.obj["local"] = local
     # Use DEFAULT_TIME if time is not provided
     ctx.obj["time"] = time if time is not None else DEFAULT_TIME
+    # Persist context override for downstream calls
+    ctx.obj["context"] = context_override
 
     # Suppress verbose if quiet is enabled
     if quiet:
         ctx.obj["verbose"] = False
 
+    # Warn users who have not completed interactive setup unless they are running it now
+    if _should_show_onboarding_reminder(ctx):
+        console.print(
+            "[warning]Complete onboarding with `pdd setup` to install tab completion and configure API keys.[/warning]"
+        )
+        ctx.obj["reminder_shown"] = True
+
+    # If --list-contexts is provided, print and exit before any other actions
+    if list_contexts:
+        try:
+            names = list_available_contexts()
+        except Exception as exc:
+            # Surface config errors as usage errors
+            raise click.UsageError(f"Failed to load .pddrc: {exc}")
+        # Print one per line; avoid Rich formatting for portability
+        for name in names:
+            click.echo(name)
+        ctx.exit(0)
+
+    # Optional early validation for --context
+    if context_override:
+        try:
+            names = list_available_contexts()
+        except Exception as exc:
+            # If .pddrc is malformed, propagate as usage error
+            raise click.UsageError(f"Failed to load .pddrc: {exc}")
+        if context_override not in names:
+            raise click.UsageError(
+                f"Unknown context '{context_override}'. Available contexts: {', '.join(names)}"
+            )
+
     # Perform auto-update check unless disabled
     if os.getenv("PDD_AUTO_UPDATE", "true").lower() != "false":
         try:
@@ -185,17 +322,23 @@ def cli(
                     style="warning"
                 )
 
-# --- Result Callback for Chained Commands ---
+    # If no subcommands were provided, show help and exit gracefully
+    if ctx.invoked_subcommand is None and not ctx.protected_args:
+        if not quiet:
+            console.print("[info]Run `pdd --help` for usage or `pdd setup` to finish onboarding.[/info]")
+        click.echo(ctx.get_help())
+        ctx.exit(0)
+
+# --- Result Callback for Command Execution Summary ---
 @cli.result_callback()
 @click.pass_context
 def process_commands(ctx: click.Context, results: List[Optional[Tuple[Any, float, str]]], **kwargs):
     """
-    Processes the results from chained commands.
-
+    Processes results returned by executed commands and prints a summary.
     Receives a list of tuples, typically (result, cost, model_name),
     or None from each command function.
     """
-    total_chain_cost = 0.0
+    total_cost = 0.0
     # Get Click's invoked subcommands attribute first
     invoked_subcommands = getattr(ctx, 'invoked_subcommands', [])
     # If Click didn't provide it (common in real runs), fall back to the list
@@ -209,11 +352,12 @@ def process_commands(ctx: click.Context, results: List[Optional[Tuple[Any, float
                     invoked_subcommands = ctx.obj.get('invoked_subcommands', []) or []
             except Exception:
                 invoked_subcommands = []
+    results = results or []
     num_commands = len(invoked_subcommands)
     num_results = len(results) # Number of results actually received
 
     if not ctx.obj.get("quiet"):
-        console.print("\n[info]--- Command Chain Execution Summary ---[/info]")
+        console.print("\n[info]--- Command Execution Summary ---[/info]")
 
     for i, result_tuple in enumerate(results):
         # Use the retrieved subcommand name (might be "Unknown Command X" in tests)
@@ -237,7 +381,7 @@ def process_commands(ctx: click.Context, results: List[Optional[Tuple[Any, float
         # Check if the result is the expected tuple structure from @track_cost or preprocess success
         elif isinstance(result_tuple, tuple) and len(result_tuple) == 3:
             _result_data, cost, model_name = result_tuple
-            total_chain_cost += cost
+            total_cost += cost
             if not ctx.obj.get("quiet"):
                 # Special handling for preprocess success message (check actual command name)
                 actual_command_name = invoked_subcommands[i] if i < num_commands else None # Get actual name if possible
@@ -256,17 +400,107 @@ def process_commands(ctx: click.Context, results: List[Optional[Tuple[Any, float
     if not ctx.obj.get("quiet"):
         # Only print total cost if at least one command potentially contributed cost
         if any(res is not None and isinstance(res, tuple) and len(res) == 3 for res in results):
-            console.print(f"[info]Total Estimated Cost for Chain:[/info] ${total_chain_cost:.6f}")
+            console.print(f"[info]Total Estimated Cost:[/info] ${total_cost:.6f}")
         # Indicate if the chain might have been incomplete due to errors
         if num_results < num_commands and not all(res is None for res in results): # Avoid printing if all failed
             console.print("[warning]Note: Chain may have terminated early due to errors.[/warning]")
         console.print("[info]-------------------------------------[/info]")
 
 
+# --- Templates Command Group ---
+@click.group(name="templates")
+def templates_group():
+    """Manage packaged and project templates."""
+    pass
+
+
+@templates_group.command("list")
+@click.option("--json", "as_json", is_flag=True, help="Output as JSON")
+@click.option("--filter", "filter_tag", type=str, default=None, help="Filter by tag")
+def templates_list(as_json: bool, filter_tag: Optional[str]):
+    try:
+        items = template_registry.list_templates(filter_tag)
+        if as_json:
+            import json as _json
+            click.echo(_json.dumps(items, indent=2))
+        else:
+            if not items:
+                console.print("[info]No templates found.[/info]")
+                return
+            console.print("[info]Available Templates:[/info]")
+            for it in items:
+                tags = ", ".join(it.get("tags", []))
+                console.print(f"- [bold]{it['name']}[/bold] ({it.get('version','')}) — {it.get('description','')} [dim]{tags}[/dim]")
+    except Exception as e:
+        handle_error(e, "templates list", False)
+
+
+@templates_group.command("show")
+@click.argument("name", type=str)
+def templates_show(name: str):
+    try:
+        data = template_registry.show_template(name)
+        summary = data.get("summary", {})
+        console.print(f"[bold]{summary.get('name','')}[/bold] — {summary.get('description','')}")
+        console.print(f"Version: {summary.get('version','')}  Tags: {', '.join(summary.get('tags',[]))}")
+        console.print(f"Language: {summary.get('language','')}  Output: {summary.get('output','')}")
+        console.print(f"Path: {summary.get('path','')}")
+        if data.get("variables"):
+            console.print("\n[info]Variables:[/info]")
+            for k, v in data["variables"].items():
+                console.print(f"- {k}: {v}")
+        if data.get("usage"):
+            console.print("\n[info]Usage:[/info]")
+            console.print(data["usage"])  # raw; CLI may format later
+        if data.get("discover"):
+            console.print("\n[info]Discover:[/info]")
+            console.print(data["discover"])  # raw dict
+        if data.get("output_schema"):
+            console.print("\n[info]Output Schema:[/info]")
+            try:
+                import json as _json
+                console.print(_json.dumps(data["output_schema"], indent=2))
+            except Exception:
+                console.print(str(data["output_schema"]))
+        if data.get("notes"):
+            console.print("\n[info]Notes:[/info]")
+            console.print(data["notes"])  # plain text
+    except Exception as e:
+        handle_error(e, "templates show", False)
+
+
+@templates_group.command("copy")
+@click.argument("name", type=str)
+@click.option("--to", "dest_dir", type=click.Path(file_okay=False), required=True)
+def templates_copy(name: str, dest_dir: str):
+    try:
+        dest = template_registry.copy_template(name, dest_dir)
+        console.print(f"[success]Copied to:[/success] {dest}")
+    except Exception as e:
+        handle_error(e, "templates copy", False)
+
+
+# Register the templates group with the main CLI.
+# Click disallows attaching a MultiCommand to a chained group via add_command,
+# so insert directly into the commands mapping after cli is defined.
+cli.commands["templates"] = templates_group
+
+
+# --- Custom Click Command Classes ---
+
+
+class GenerateCommand(click.Command):
+    """Ensure help shows PROMPT_FILE as required even when validated at runtime."""
+
+    def collect_usage_pieces(self, ctx: click.Context) -> List[str]:
+        pieces = super().collect_usage_pieces(ctx)
+        return ["PROMPT_FILE" if piece == "[PROMPT_FILE]" else piece for piece in pieces]
+
+
 # --- Command Definitions ---
 
-@cli.command("generate")
-@click.argument("prompt_file", type=click.Path(exists=True, dir_okay=False))
+@cli.command("generate", cls=GenerateCommand)
+@click.argument("prompt_file", required=False, type=click.Path(exists=True, dir_okay=False))
 @click.option(
     "--output",
     type=click.Path(writable=True),
@@ -294,18 +528,40 @@ def process_commands(ctx: click.Context, results: List[Optional[Tuple[Any, float
     multiple=True,
     help="Set template variable (KEY=VALUE) or read KEY from env",
 )
+@click.option(
+    "--template",
+    "template_name",
+    type=str,
+    default=None,
+    help="Use a packaged/project template by name (e.g., architecture/architecture_json)",
+)
 @click.pass_context
 @track_cost
 def generate(
     ctx: click.Context,
-    prompt_file: str,
+    prompt_file: Optional[str],
     output: Optional[str],
     original_prompt_file_path: Optional[str],
     incremental_flag: bool,
     env_kv: Tuple[str, ...],
+    template_name: Optional[str],
 ) -> Optional[Tuple[str, float, str]]:
     """Generate code from a prompt file."""
     try:
+        # Resolve template to a prompt path when requested
+        if template_name and prompt_file:
+            raise click.UsageError("Provide either --template or a PROMPT_FILE path, not both.")
+        if template_name:
+            try:
+                from . import template_registry as _tpl
+                meta = _tpl.load_template(template_name)
+                prompt_file = meta.get("path")
+                if not prompt_file:
+                    raise click.UsageError(f"Template '{template_name}' did not return a valid path")
+            except Exception as e:
+                raise click.UsageError(f"Failed to load template '{template_name}': {e}")
+        if not template_name and not prompt_file:
+            raise click.UsageError("Missing PROMPT_FILE. To use a template, pass --template NAME instead.")
         # Parse -e/--env arguments into a dict
         env_vars: Dict[str, str] = {}
         import os as _os
@@ -326,7 +582,7 @@ def generate(
                             console.print(f"[warning]-e {key} not found in environment; skipping[/warning]")
         generated_code, incremental, total_cost, model_name = code_generator_main(
             ctx=ctx,
-            prompt_file=prompt_file,
+            prompt_file=prompt_file,  # resolved template path or user path
             output=output,
             original_prompt_file_path=original_prompt_file_path,
             force_incremental_flag=incremental_flag,
@@ -1288,6 +1544,22 @@ def install_completion_cmd(ctx: click.Context) -> None: # Return type remains No
         # Do not return anything, as the callback expects None or a tuple
 
 
+@cli.command("setup")
+@click.pass_context
+def setup_cmd(ctx: click.Context) -> None:
+    """Run the interactive setup utility and install shell completion."""
+    command_name = "setup"
+    quiet_mode = ctx.obj.get("quiet", False)
+
+    try:
+        install_completion(quiet=quiet_mode)
+        _run_setup_utility()
+        if not quiet_mode:
+            console.print("[success]Setup completed. Restart your shell or source your RC file to apply changes.[/success]")
+    except Exception as exc:
+        handle_error(exc, command_name, quiet_mode)
+
+
 # --- Entry Point ---
 if __name__ == "__main__":
     cli()

pdd/cmd_test_main.py

@@ -88,6 +88,7 @@ def cmd_test_main(
             quiet=ctx.obj["quiet"],
             command="test",
             command_options=command_options,
+            context_override=ctx.obj.get('context')
         )
     except Exception as exception:
         # Catching a general exception is necessary here to handle a wide range of