pdd-cli 0.0.118__py3-none-any.whl → 0.0.121__py3-none-any.whl

pdd/commands/analysis.py

@@ -5,7 +5,7 @@ Analysis commands (detect-change, conflicts, bug, crash, trace).
 """
 import os
 import click
-from typing import Optional, Tuple, List
+from typing import Optional, Tuple, List, Dict, Any
 
 from ..detect_change_main import detect_change_main
 from ..conflicts_main import conflicts_main
@@ -15,6 +15,11 @@ from ..crash_main import crash_main
 from ..trace_main import trace_main
 from ..track_cost import track_cost
 from ..core.errors import handle_error
+from ..operation_log import log_operation
+
+def get_context_obj(ctx: click.Context) -> Dict[str, Any]:
+    """Safely retrieve the context object, defaulting to empty dict if None."""
+    return ctx.obj or {}
 
 @click.command("detect")
 @click.argument("files", nargs=-1, type=click.Path(exists=True, dir_okay=False))
@@ -28,8 +33,8 @@ from ..core.errors import handle_error
 @track_cost
 def detect_change(
     ctx: click.Context,
-    files: Tuple[str, ...],
-    output: Optional[str],
+    files: Tuple[str, ...] = (),
+    output: Optional[str] = None,
 ) -> Optional[Tuple[List, float, str]]:
     """Detect if prompts need to be changed based on a description.
     
@@ -53,7 +58,7 @@ def detect_change(
     except (click.Abort, click.ClickException):
         raise
     except Exception as exception:
-        handle_error(exception, "detect", ctx.obj.get("quiet", False))
+        handle_error(exception, "detect", get_context_obj(ctx).get("quiet", False))
         return None
 
 
@@ -72,7 +77,7 @@ def conflicts(
     ctx: click.Context,
     prompt1: str,
     prompt2: str,
-    output: Optional[str],
+    output: Optional[str] = None,
 ) -> Optional[Tuple[List, float, str]]:
     """Check for conflicts between two prompt files."""
     try:
@@ -81,13 +86,13 @@ def conflicts(
             prompt1=prompt1,
             prompt2=prompt2,
             output=output,
-            verbose=ctx.obj.get("verbose", False),
+            verbose=get_context_obj(ctx).get("verbose", False),
         )
         return result, total_cost, model_name
     except (click.Abort, click.ClickException):
         raise
     except Exception as exception:
-        handle_error(exception, "conflicts", ctx.obj.get("quiet", False))
+        handle_error(exception, "conflicts", get_context_obj(ctx).get("quiet", False))
         return None
 
 
@@ -127,12 +132,12 @@ def conflicts(
 @track_cost
 def bug(
     ctx: click.Context,
-    manual: bool,
-    args: Tuple[str, ...],
-    output: Optional[str],
-    language: str,
-    timeout_adder: float,
-    no_github_state: bool,
+    manual: bool = False,
+    args: Tuple[str, ...] = (),
+    output: Optional[str] = None,
+    language: str = "Python",
+    timeout_adder: float = 0.0,
+    no_github_state: bool = False,
 ) -> Optional[Tuple[str, float, str]]:
     """Generate a unit test (manual) or investigate a bug (agentic).
 
@@ -143,6 +148,7 @@ def bug(
         pdd bug --manual PROMPT_FILE CODE_FILE PROGRAM_FILE CURRENT_OUTPUT DESIRED_OUTPUT
     """
     try:
+        obj = get_context_obj(ctx)
         if manual:
             if len(args) != 5:
                 raise click.UsageError(
@@ -179,8 +185,8 @@ def bug(
             
             success, message, cost, model, changed_files = run_agentic_bug(
                 issue_url=issue_url,
-                verbose=ctx.obj.get("verbose", False),
-                quiet=ctx.obj.get("quiet", False),
+                verbose=obj.get("verbose", False),
+                quiet=obj.get("quiet", False),
                 timeout_adder=timeout_adder,
                 use_github_state=not no_github_state,
             )
@@ -191,7 +197,7 @@ def bug(
     except (click.Abort, click.ClickException):
         raise
     except Exception as exception:
-        handle_error(exception, "bug", ctx.obj.get("quiet", False))
+        handle_error(exception, "bug", get_context_obj(ctx).get("quiet", False))
         return None
 
 
@@ -231,6 +237,7 @@ def bug(
     help="Maximum cost allowed for the fixing process (default: 5.0).",
 )
 @click.pass_context
+@log_operation("crash", clears_run_report=True)
 @track_cost
 def crash(
     ctx: click.Context,
@@ -238,11 +245,11 @@ def crash(
     code_file: str,
     program_file: str,
     error_file: str,
-    output: Optional[str],
-    output_program: Optional[str],
-    loop: bool,
-    max_attempts: Optional[int],
-    budget: Optional[float],
+    output: Optional[str] = None,
+    output_program: Optional[str] = None,
+    loop: bool = False,
+    max_attempts: Optional[int] = None,
+    budget: Optional[float] = None,
 ) -> Optional[Tuple[str, float, str]]:
     """Analyze a crash and fix the code and program."""
     try:
@@ -265,7 +272,7 @@ def crash(
     except (click.Abort, click.ClickException):
         raise
     except Exception as exception:
-        handle_error(exception, "crash", ctx.obj.get("quiet", False))
+        handle_error(exception, "crash", get_context_obj(ctx).get("quiet", False))
         return None
 
 
@@ -286,7 +293,7 @@ def trace(
     prompt_file: str,
     code_file: str,
     code_line: int,
-    output: Optional[str],
+    output: Optional[str] = None,
 ) -> Optional[Tuple[str, float, str]]:
     """Trace execution flow back to the prompt."""
     try:
@@ -302,5 +309,5 @@ def trace(
     except (click.Abort, click.ClickException):
         raise
     except Exception as exception:
-        handle_error(exception, "trace", ctx.obj.get("quiet", False))
-        return None
+        handle_error(exception, "trace", get_context_obj(ctx).get("quiet", False))
+        return None

pdd/commands/connect.py

@@ -8,13 +8,44 @@ REST server to enable the web frontend to interact with PDD.
 from __future__ import annotations
 
 import asyncio
+import errno
 import os
+import socket
 import webbrowser
 from pathlib import Path
 from typing import Optional
 
 import click
 
+
+# Default port and range for auto-assignment
+DEFAULT_PORT = 9876
+PORT_RANGE_START = 9876
+PORT_RANGE_END = 9899  # Try up to 24 ports
+
+
+def is_port_available(port: int, host: str = "127.0.0.1") -> bool:
+    """Check if a port is available for binding."""
+    try:
+        with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:
+            s.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
+            s.bind((host, port))
+            return True
+    except OSError as exc:
+        # If we lack permission to bind (common in sandboxed environments),
+        # treat availability as unknown and allow the caller to proceed.
+        if exc.errno in (errno.EACCES, errno.EPERM):
+            return True
+        return False
+
+
+def find_available_port(start_port: int, end_port: int, host: str = "127.0.0.1") -> Optional[int]:
+    """Find an available port in the given range."""
+    for port in range(start_port, end_port + 1):
+        if is_port_available(port, host):
+            return port
+    return None
+
 # Handle optional dependencies - uvicorn may not be installed
 try:
     import uvicorn
@@ -131,6 +162,43 @@ def connect(
                 fg="yellow"
             ))
 
+    # 2.5 Smart Port Detection
+    # Check if user explicitly specified a port
+    port_source = ctx.get_parameter_source("port")
+    user_specified_port = port_source == click.core.ParameterSource.COMMANDLINE
+
+    # For port checking, use the effective bind host
+    check_host = "0.0.0.0" if host == "0.0.0.0" else "127.0.0.1"
+
+    if not is_port_available(port, check_host):
+        if user_specified_port:
+            # User explicitly requested this port, show error
+            click.echo(click.style(
+                f"Error: Port {port} is already in use.",
+                fg="red", bold=True
+            ))
+            click.echo("Please specify a different port with --port or stop the process using this port.")
+            ctx.exit(1)
+        else:
+            # Auto-detect an available port
+            click.echo(click.style(
+                f"Port {port} is in use, looking for an available port...",
+                fg="yellow"
+            ))
+            available_port = find_available_port(PORT_RANGE_START, PORT_RANGE_END, check_host)
+            if available_port is None:
+                click.echo(click.style(
+                    f"Error: No available ports found in range {PORT_RANGE_START}-{PORT_RANGE_END}.",
+                    fg="red", bold=True
+                ))
+                click.echo("Please specify a port manually with --port or free up a port in this range.")
+                ctx.exit(1)
+            port = available_port
+            click.echo(click.style(
+                f"Using port {port} instead.",
+                fg="green"
+            ))
+
     # 3. Determine URLs
     # The server URL is where the API lives
     server_url = f"http://{host}:{port}"
@@ -287,4 +355,4 @@ def connect(
             except Exception as e:
                 click.echo(click.style(f"Warning: Error during session cleanup: {e}", fg="yellow"))
 
-        click.echo(click.style("Goodbye!", fg="blue"))
+        click.echo(click.style("Goodbye!", fg="blue"))

pdd/commands/fix.py

@@ -1,5 +1,6 @@
 from __future__ import annotations
 
+import os
 import sys
 import click
 from typing import Optional, Tuple, Any
@@ -9,6 +10,7 @@ from rich.console import Console
 from ..fix_main import fix_main
 from ..agentic_e2e_fix import run_agentic_e2e_fix
 from ..track_cost import track_cost
+from ..operation_log import log_operation
 from ..core.errors import handle_error
 
 console = Console()
@@ -31,6 +33,7 @@ console = Console()
 @click.option("--auto-submit", is_flag=True, help="Automatically submit example if tests pass.")
 @click.option("--agentic-fallback/--no-agentic-fallback", default=True, help="Enable agentic fallback in loop mode.")
 @click.pass_context
+@log_operation(operation="fix", clears_run_report=True)
 @track_cost
 def fix(
     ctx: click.Context,
@@ -72,8 +75,8 @@ def fix(
                 console.print("[yellow]Warning: Extra arguments ignored in Agentic E2E Fix mode.[/yellow]")
             
             issue_url = args[0]
-            verbose = ctx.obj.get("verbose", False)
-            quiet = ctx.obj.get("quiet", False)
+            verbose = ctx.obj.get("verbose", False) if ctx.obj else False
+            quiet = ctx.obj.get("quiet", False) if ctx.obj else False
             
             # Call the agentic fix workflow
             success, message, cost, model, _ = run_agentic_e2e_fix(
@@ -97,17 +100,31 @@ def fix(
         # --- Manual Mode ---
         else:
             # Validate arguments for manual mode
-            # Expected structure: PROMPT_FILE CODE_FILE UNIT_TEST_FILE [UNIT_TEST_FILE...] ERROR_FILE
-            if len(args) < 4:
-                raise click.UsageError(
-                    "Manual mode requires at least 4 arguments: PROMPT_FILE CODE_FILE UNIT_TEST_FILE... ERROR_FILE"
-                )
+            # Expected structure:
+            # - Loop mode: PROMPT_FILE CODE_FILE UNIT_TEST_FILE [UNIT_TEST_FILE...]
+            # - Non-loop mode: PROMPT_FILE CODE_FILE UNIT_TEST_FILE [UNIT_TEST_FILE...] ERROR_FILE
+            min_args = 3 if loop else 4
+            if len(args) < min_args:
+                if loop:
+                    raise click.UsageError(
+                        "Loop mode requires at least 3 arguments: PROMPT_FILE CODE_FILE UNIT_TEST_FILE..."
+                    )
+                else:
+                    raise click.UsageError(
+                        "Non-loop mode requires at least 4 arguments: PROMPT_FILE CODE_FILE UNIT_TEST_FILE... ERROR_FILE"
+                    )
 
             prompt_file = args[0]
             code_file = args[1]
-            error_file = args[-1]
-            # All arguments between code file and error file are treated as unit test files
-            unit_test_files = args[2:-1]
+
+            # In loop mode, error_file is optional (generated during loop)
+            # In non-loop mode, last argument is the error_file
+            if loop:
+                error_file = None
+                unit_test_files = args[2:]  # All remaining args are test files
+            else:
+                error_file = args[-1]
+                unit_test_files = args[2:-1]  # All args between code file and error file
 
             total_cost = 0.0
             last_model = "unknown"
@@ -156,8 +173,9 @@ def fix(
             else:
                 return f"Some files failed to fix.\n{summary_str}", total_cost, last_model
 
-    except click.Abort:
+    except (click.Abort, click.UsageError, click.BadArgumentUsage, click.FileError, click.BadParameter):
         raise
     except Exception as e:
-        handle_error(e)
-        return None
+        quiet = ctx.obj.get("quiet", False) if ctx.obj else False
+        handle_error(e, "fix", quiet)
+        sys.exit(1)

pdd/commands/generate.py

@@ -1,6 +1,7 @@
 """
 Generate, test, and example commands.
 """
+from __future__ import annotations
 import click
 from typing import Dict, Optional, Tuple, List
 
@@ -9,6 +10,7 @@ from ..context_generator_main import context_generator_main
 from ..cmd_test_main import cmd_test_main
 from ..track_cost import track_cost
 from ..core.errors import handle_error, console
+from ..operation_log import log_operation
 
 class GenerateCommand(click.Command):
     """Ensure help shows PROMPT_FILE as required even when validated at runtime."""
@@ -69,6 +71,7 @@ class GenerateCommand(click.Command):
     help="Do not automatically include test files found in the default tests directory.",
 )
 @click.pass_context
+@log_operation("generate", clears_run_report=True, updates_fingerprint=True)
 @track_cost
 def generate(
     ctx: click.Context,
@@ -159,6 +162,7 @@ def generate(
     help="Specify where to save the generated example code (file or directory).",
 )
 @click.pass_context
+@log_operation("example", updates_fingerprint=True)
 @track_cost
 def example(
     ctx: click.Context, 
@@ -222,6 +226,7 @@ def example(
     help="Merge new tests with existing test file instead of creating a separate file.",
 )
 @click.pass_context
+@log_operation("test", updates_run_report=True)
 @track_cost
 def test(
     ctx: click.Context,

pdd/commands/modify.py

@@ -14,6 +14,7 @@ from ..agentic_change import run_agentic_change
 from ..update_main import update_main
 from ..track_cost import track_cost
 from ..core.errors import handle_error
+from ..operation_log import log_operation
 
 console = Console()
 
@@ -123,7 +124,7 @@ def change(
                     raise click.UsageError("INPUT_PROMPT_FILE is required when not using --csv")
                 else:
                     raise click.UsageError(
-                        "Manual mode requires 2 or 3 arguments: CHANGE_PROMPT INPUT_CODE [INPUT_PROMPT]"
+                        "Manual mode requires 3 arguments: CHANGE_PROMPT INPUT_CODE INPUT_PROMPT"
                     )
 
             # Validate file existence
@@ -191,6 +192,7 @@ def change(
 @click.option("--output", help="Output path for the updated prompt.")
 @click.option("--simple", is_flag=True, default=False, help="Use legacy simple update.")
 @click.pass_context
+@log_operation(operation="update", clears_run_report=True)
 @track_cost
 def update(
     ctx: click.Context,
@@ -209,18 +211,55 @@ def update(
     """
     ctx.ensure_object(dict)
     try:
-        # Determine mode based on argument count
-        is_repo_mode = len(files) == 0
+        # Handle argument counts per modify_python.prompt spec (aligned with README)
+        if len(files) == 0:
+            # Repo-wide mode
+            is_repo_mode = True
+            input_prompt_file = None
+            modified_code_file = None
+            input_code_file = None
+        elif len(files) == 1:
+            # Regeneration mode: just the code file
+            is_repo_mode = False
+            input_prompt_file = None
+            modified_code_file = files[0]
+            input_code_file = None
+        elif len(files) == 2:
+            # Git-based update: prompt + modified_code (requires --git)
+            if not git:
+                raise click.UsageError(
+                    "Two arguments require --git flag: pdd update --git <prompt> <modified_code>"
+                )
+            is_repo_mode = False
+            input_prompt_file = files[0]
+            modified_code_file = files[1]
+            input_code_file = None
+        elif len(files) == 3:
+            # Manual update: prompt + modified_code + original_code
+            if git:
+                raise click.UsageError(
+                    "Cannot use --git with 3 arguments (--git and original_code are mutually exclusive)"
+                )
+            is_repo_mode = False
+            input_prompt_file = files[0]
+            modified_code_file = files[1]
+            input_code_file = files[2]
+        else:
+            raise click.UsageError("Too many arguments. Max 3: <prompt> <modified_code> <original_code>")
 
         # Validate mode-specific options
         if is_repo_mode:
             # Repo-wide mode: --git and --output are not allowed
             if git:
                 raise click.UsageError(
-                    "Cannot use file-specific arguments or flags like --git in repository-wide mode"
+                    "Cannot use --git in repository-wide mode"
+                )
+            if output:
+                raise click.UsageError(
+                    "Cannot use --output in repository-wide mode"
                 )
         else:
-            # Single-file mode: --extensions and --directory are not allowed
+            # File modes: --extensions and --directory are not allowed
             if extensions:
                 raise click.UsageError(
                     "--extensions can only be used in repository-wide mode"
@@ -230,15 +269,12 @@ def update(
                     "--directory can only be used in repository-wide mode"
                 )
 
-        # In single-file mode, the one arg is the modified code file
-        modified_code_file = files[0] if len(files) > 0 else None
-
         # Call update_main with correct parameters
         result, cost, model = update_main(
             ctx=ctx,
-            input_prompt_file=None,
+            input_prompt_file=input_prompt_file,
             modified_code_file=modified_code_file,
-            input_code_file=None,
+            input_code_file=input_code_file,
             output=output,
             use_git=git,
             repo=is_repo_mode,
@@ -253,4 +289,4 @@ def update(
         raise
     except Exception as e:
         handle_error(e, "update", ctx.obj.get("quiet", False))
-        return None
+        return None

pdd/commands/utility.py

@@ -1,24 +1,27 @@
 """
 Utility commands (install_completion, verify/fix-verification).
 """
+from __future__ import annotations
 import click
-from typing import Optional, Tuple
+from typing import Optional, Tuple, Dict, Any
 
 from ..fix_verification_main import fix_verification_main
 from ..track_cost import track_cost
 from ..core.errors import handle_error
+from ..operation_log import log_operation
 
 @click.command("install_completion")
 @click.pass_context
-def install_completion_cmd(ctx: click.Context):
+def install_completion_cmd(ctx: click.Context) -> None:
     """Install shell completion for the PDD CLI."""
+    # Safely retrieve quiet flag, defaulting to False if ctx.obj is None
+    quiet = (ctx.obj or {}).get("quiet", False)
     try:
         from .. import cli as cli_module  # Import parent module for proper patching
-        quiet = ctx.obj.get("quiet", False)
         # Call through cli_module so patches to pdd.cli.install_completion work
         cli_module.install_completion(quiet=quiet)
     except Exception as e:
-        handle_error(e, "install_completion", ctx.obj.get("quiet", False))
+        handle_error(e, "install_completion", quiet)
 
 
 @click.command("verify")
@@ -64,6 +67,7 @@ def install_completion_cmd(ctx: click.Context):
     help="Enable agentic fallback if the primary fix mechanism fails.",
 )
 @click.pass_context
+@log_operation(operation="verify", clears_run_report=True, updates_run_report=True)
 @track_cost
 def verify(
     ctx: click.Context,
@@ -76,7 +80,7 @@ def verify(
     max_attempts: int,
     budget: float,
     agentic_fallback: bool,
-) -> Optional[Tuple]:
+) -> Optional[Tuple[Dict[str, Any], float, str]]:
     """Verify code using a verification program."""
     try:
         # verify command implies a loop if max_attempts > 1, but let's enable loop by default
@@ -106,5 +110,6 @@ def verify(
     except click.Abort:
         raise
     except Exception as exception:
-        handle_error(exception, "verify", ctx.obj.get("quiet", False))
-        return None
+        quiet = (ctx.obj or {}).get("quiet", False)
+        handle_error(exception, "verify", quiet)
+        return None

pdd/core/cli.py

@@ -262,11 +262,17 @@ class PDDCLI(click.Group):
     help="List available contexts from .pddrc and exit.",
 )
 @click.option(
-    "--core-dump",
+    "--core-dump/--no-core-dump",
     "core_dump",
-    is_flag=True,
-    default=False,
-    help="Write a JSON core dump for this run into .pdd/core_dumps (for bug reports).",
+    default=True,
+    help="Write a JSON core dump for this run into .pdd/core_dumps (default: on). Use --no-core-dump to disable.",
+)
+@click.option(
+    "--keep-core-dumps",
+    "keep_core_dumps",
+    type=click.IntRange(min=0),
+    default=10,
+    help="Number of core dumps to keep (default: 10, min: 0). Older dumps are garbage collected after each dump write.",
 )
 @click.version_option(version=__version__, package_name="pdd-cli")
 @click.pass_context
@@ -284,6 +290,7 @@ def cli(
     context_override: Optional[str],
     list_contexts: bool,
     core_dump: bool,
+    keep_core_dumps: int,
 ):
     """
     Main entry point for the PDD CLI. Handles global options and initializes context.
@@ -317,6 +324,12 @@ def cli(
     # Persist context override for downstream calls
     ctx.obj["context"] = context_override
     ctx.obj["core_dump"] = core_dump
+    ctx.obj["keep_core_dumps"] = keep_core_dumps
+
+    # Garbage collect old core dumps on every CLI invocation (Issue #231)
+    # This runs regardless of --no-core-dump to ensure cleanup always happens
+    from .dump import garbage_collect_core_dumps
+    garbage_collect_core_dumps(keep=keep_core_dumps)
 
     # Set up terminal output capture if core_dump is enabled
     if core_dump: