feat: add configurable output directory support

InertSloth · InertSloth · commit 724e72ff4e5a · 2025-12-03T20:36:44.000-05:00
- Add output.directory field to configuration
- Create resolve_output_path_from_config() helper function
- Update api.py and build.py to use new helper
- Add validation for output.directory field
- Add tests for directory + name and directory-only configurations
- Update documentation with output.directory examples
- Mark feature as completed in ROADMAP.md
diff --git a/ROADMAP.md b/ROADMAP.md
@@ -22,7 +22,7 @@ Some of these we just want to consider, and may not want to implement.
 
 ### Phase 2: Configuration System
 - **Config File Support**: `.zipbundler.py`, `.zipbundler.jsonc`, or `pyproject.toml` integration (searches current directory and parent directories) ✅
-- **Output Path**: Configurable output directory and filename
+- **Output Path**: Configurable output directory and filename ✅
 - **Entry Point Configuration**: Define entry points in config file
 - **Metadata Auto-Detection**: `init` command auto-detects metadata from `pyproject.toml` when creating config files ✅
 
@@ -59,7 +59,8 @@ Some of these we just want to consider, and may not want to implement.
   // Output configuration
   "output": {
     "path": "dist/my_package.zip",
-    "name": "my_package"  // Optional: used to generate default path (dist/{name}.pyz) when path is not specified
+    "directory": "build",  // Optional: output directory (default: "dist")
+    "name": "my_package"  // Optional: used to generate default path ({directory}/{name}.pyz) when path is not specified
   },
   
   // Entry point for executable zip
diff --git a/docs/configuration.md b/docs/configuration.md
@@ -70,13 +70,15 @@ Output configuration for the zip file.
 {
   "output": {
     "path": "dist/my_package.zip",
+    "directory": "build",  // Optional: output directory (default: "dist")
     "name": "my_package"  // Optional: override zip name
   }
 }
 ```
 
-- `path`: Full path to output zip file (default: `dist/{package_name}.zip`)
-- `name`: Optional name override for the zip file
+- `path`: Full path to output zip file (takes precedence over `directory` and `name`)
+- `directory`: Output directory (default: `"dist"`). Used with `name` to generate path when `path` is not specified
+- `name`: Optional name override for the zip file. When used with `directory`, generates `{directory}/{name}.pyz`
 
 #### `entry_point` (optional)
 Entry point for executable zip files (equivalent to `-m` / `--main` in zipapp-style CLI).
@@ -175,6 +177,7 @@ version = "1.0.0"
   ],
   "output": {
     "path": "dist/my_package.zip",
+    "directory": "build",
     "name": "my_package"
   },
   "entry_point": "my_package.__main__:main",
diff --git a/src/zipbundler/api.py b/src/zipbundler/api.py
@@ -14,7 +14,12 @@
 from .actions import watch_for_changes
 from .build import build_zipapp, extract_archive_to_tempdir, list_files
 from .commands.build import extract_entry_point_code
-from .commands.validate import find_config, load_config, validate_config_structure
+from .commands.validate import (
+    find_config,
+    load_config,
+    resolve_output_path_from_config,
+    validate_config_structure,
+)
 from .commands.zipapp_style import is_archive_file
 from .constants import DEFAULT_WATCH_INTERVAL
 from .logs import getAppLogger
@@ -289,17 +294,7 @@ def build_zip(  # noqa: C901, PLR0912, PLR0913, PLR0915
         # Extract output path from config
         if output_path is None:
             output_config: dict[str, Any] | None = config.get("output")
-            if output_config:
-                output_path_str: str | None = output_config.get("path")
-                output_name: str | None = output_config.get("name")
-                if output_path_str:
-                    output_path = Path(output_path_str)
-                elif output_name:
-                    output_path = Path(f"dist/{output_name}.pyz")
-                else:
-                    output_path = Path("dist/bundle.pyz")
-            else:
-                output_path = Path("dist/bundle.pyz")
+            output_path = resolve_output_path_from_config(output_config)
 
         # Extract options from config
         options: dict[str, Any] | None = config.get("options")
@@ -402,7 +397,7 @@ def build_zip(  # noqa: C901, PLR0912, PLR0913, PLR0915
     )
 
 
-def watch(  # noqa: C901, PLR0912
+def watch(
     config_path: str | Path | None = None,
     *,
     packages: list[str] | None = None,
@@ -448,23 +443,13 @@ def watch(  # noqa: C901, PLR0912
             exclude = config.get("exclude")
         if output_path is None:
             output_config: dict[str, Any] | None = config.get("output")
-            if output_config:
-                output_path_str: str | None = output_config.get("path")
-                output_name: str | None = output_config.get("name")
-                if output_path_str:
-                    output_path = Path(output_path_str)
-                elif output_name:
-                    output_path = Path(f"dist/{output_name}.pyz")
-                else:
-                    output_path = Path("dist/bundle.pyz")
-            else:
-                output_path = Path("dist/bundle.pyz")
+            output_path = resolve_output_path_from_config(output_config)
 
     if not packages:
         msg = "packages must be provided if config_path is not specified"
         raise ValueError(msg)
     if output_path is None:
-        output_path = Path("dist/bundle.pyz")
+        output_path = resolve_output_path_from_config(None)
 
     # Resolve output path relative to cwd
     if not isinstance(output_path, Path):
diff --git a/src/zipbundler/commands/build.py b/src/zipbundler/commands/build.py
@@ -14,6 +14,7 @@
 from zipbundler.commands.validate import (
     find_config,
     load_config,
+    resolve_output_path_from_config,
     validate_config_structure,
 )
 from zipbundler.logs import getAppLogger
@@ -323,29 +324,12 @@ def handle_build_command(args: argparse.Namespace) -> int:  # noqa: C901, PLR091
 
         # Extract output path
         output_config: dict[str, Any] | None = config.get("output")
-        if output_config:  # pyright: ignore[reportUnnecessaryIsInstance]
-            output_path_str: str | None = output_config.get("path")
-            output_name: str | None = output_config.get("name")
-        else:
-            output_path_str = None
-            output_name = None
-
-        if not output_path_str:
-            # Default output path
-            if output_name:
-                # Use output.name to generate default path
-                output_path_str = f"dist/{output_name}.pyz"
-                logger.debug(
-                    "No output path specified, using output.name: %s",
-                    output_path_str,
-                )
-            else:
-                output_path_str = "dist/bundle.pyz"
-                logger.debug(
-                    "No output path specified, using default: %s", output_path_str
-                )
-
-        output = (cwd / output_path_str).resolve()
+        output_path = resolve_output_path_from_config(output_config)
+        logger.debug(
+            "Resolved output path from config: %s",
+            output_path,
+        )
+        output = (cwd / output_path).resolve()
 
         # Extract entry point
         entry_point_str: str | None = config.get("entry_point")
diff --git a/src/zipbundler/commands/validate.py b/src/zipbundler/commands/validate.py
@@ -250,6 +250,46 @@ def _validate_output_path(output_path: str, cwd: Path) -> tuple[bool, str]:
         return False, msg
 
 
+def resolve_output_path_from_config(
+    output_config: dict[str, Any] | None,
+    default_directory: str = "dist",
+    default_name: str = "bundle",
+) -> Path:
+    """Resolve output path from config output section.
+
+    Handles:
+    - output.path: Full path (takes precedence)
+    - output.directory + output.name: Directory and filename
+    - output.name: Filename only (uses default_directory)
+    - None: Uses default_directory and default_name
+
+    Args:
+        output_config: Output configuration dict with optional 'path', 'directory',
+            'name'
+        default_directory: Default directory if not specified (default: "dist")
+        default_name: Default filename (without extension) if not specified
+            (default: "bundle")
+
+    Returns:
+        Resolved Path object
+    """
+    if not output_config:
+        return Path(f"{default_directory}/{default_name}.pyz")
+
+    output_path_str: str | None = output_config.get("path")
+    if output_path_str:
+        return Path(output_path_str)
+
+    output_directory: str | None = output_config.get("directory")
+    output_name: str | None = output_config.get("name")
+
+    # Use directory from config or default, name from config or default
+    directory = output_directory if output_directory is not None else default_directory
+    name = output_name if output_name is not None else default_name
+
+    return Path(f"{directory}/{name}.pyz")
+
+
 def _validate_packages_field(
     config: dict[str, Any],
     errors: list[str],
@@ -334,6 +374,13 @@ def _validate_output_field(
             msg = "Field 'output.name' must be a string"
             warnings.append(msg)
 
+    # Validate output.directory field (optional)
+    if "directory" in output:
+        output_directory: Any = output["directory"]  # pyright: ignore[reportUnknownVariableType]
+        if not isinstance(output_directory, str):
+            msg = "Field 'output.directory' must be a string"
+            warnings.append(msg)
+
 
 def _validate_shebang_option(
     options: dict[str, Any],
diff --git a/tests/50_core/test_build_command.py b/tests/50_core/test_build_command.py
@@ -299,6 +299,99 @@ def test_cli_build_command_output_name_ignored_with_path(
         os.chdir(original_cwd)
 
 
+def test_cli_build_command_output_directory(tmp_path: Path) -> None:
+    """Test build command with output.directory configuration."""
+    original_cwd = Path.cwd()
+    try:
+        os.chdir(tmp_path)
+
+        # Create a package structure
+        src_dir = tmp_path / "src" / "mypackage"
+        src_dir.mkdir(parents=True)
+        (src_dir / "__init__.py").write_text("")
+        (src_dir / "module.py").write_text("def func():\n    pass\n")
+
+        # Create config file with output.directory and output.name
+        config_file = tmp_path / ".zipbundler.jsonc"
+        config_file.write_text(
+            """{
+  "packages": ["src/mypackage/**/*.py"],
+  "output": {
+    "directory": "build",
+    "name": "my_package"
+  }
+}
+""",
+            encoding="utf-8",
+        )
+
+        # Handle both module and function cases (runtime mode swap)
+        main_func = mod_main if callable(mod_main) else mod_main.main
+        code = main_func(["build"])
+
+        # Verify exit code is 0
+        assert code == 0
+
+        # Verify zip file was created in the custom directory
+        output_file = tmp_path / "build" / "my_package.pyz"
+        assert output_file.exists()
+
+        # Verify zip file is valid and contains expected files
+        with zipfile.ZipFile(output_file, "r") as zf:
+            names = zf.namelist()
+            assert any("mypackage/__init__.py" in name for name in names)
+            assert any("mypackage/module.py" in name for name in names)
+
+        # Verify default dist directory was NOT used
+        assert not (tmp_path / "dist" / "my_package.pyz").exists()
+    finally:
+        os.chdir(original_cwd)
+
+
+def test_cli_build_command_output_directory_only(tmp_path: Path) -> None:
+    """Test build command with only output.directory (no name)."""
+    original_cwd = Path.cwd()
+    try:
+        os.chdir(tmp_path)
+
+        # Create a package structure
+        src_dir = tmp_path / "src" / "mypackage"
+        src_dir.mkdir(parents=True)
+        (src_dir / "__init__.py").write_text("")
+        (src_dir / "module.py").write_text("def func():\n    pass\n")
+
+        # Create config file with only output.directory
+        config_file = tmp_path / ".zipbundler.jsonc"
+        config_file.write_text(
+            """{
+  "packages": ["src/mypackage/**/*.py"],
+  "output": {
+    "directory": "output"
+  }
+}
+""",
+            encoding="utf-8",
+        )
+
+        # Handle both module and function cases (runtime mode swap)
+        main_func = mod_main if callable(mod_main) else mod_main.main
+        code = main_func(["build"])
+
+        # Verify exit code is 0
+        assert code == 0
+
+        # Verify zip file was created in custom directory with default name
+        output_file = tmp_path / "output" / "bundle.pyz"
+        assert output_file.exists()
+
+        # Verify zip file is valid
+        with zipfile.ZipFile(output_file, "r") as zf:
+            names = zf.namelist()
+            assert any("mypackage/__init__.py" in name for name in names)
+    finally:
+        os.chdir(original_cwd)
+
+
 def test_cli_build_command_invalid_config(tmp_path: Path) -> None:
     """Test build command with invalid config (missing packages)."""
     original_cwd = Path.cwd()
