pysfi 0.1.7__py3-none-any.whl → 0.1.11__py3-none-any.whl

sfi/pypack/pypack.py

@@ -0,0 +1,1142 @@
+"""Package Workflow - Advanced Python project packaging tool with workflow orchestration.
+
+This module provides a comprehensive packaging solution that integrates pyprojectparse,
+pysourcepack, pyembedinstall, and pyloadergen tools through a workflow engine to achieve
+mixed serial and parallel execution for optimal efficiency.
+"""
+
+from __future__ import annotations
+
+import argparse
+import asyncio
+import json
+import logging
+import platform
+import shutil
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+from sfi.pyprojectparse.pyprojectparse import Project, Solution
+from sfi.pysourcepack.pysourcepack import pack_project
+from sfi.workflowengine.workflowengine import (
+    CPUTask,
+    IOTask,
+    SerialTask,
+    WorkflowEngine,
+)
+
+logging.basicConfig(
+    level=logging.INFO, format="%(asctime)s - %(levelname)s - %(message)s"
+)
+logger = logging.getLogger(__name__)
+cwd = Path.cwd()
+is_windows = platform.system() == "Windows"
+ext = ".exe" if is_windows else ""
+
+__version__ = "1.0.0"
+__build__ = "20260120"
+
+
+@dataclass
+class WorkflowConfig:
+    """Configuration for package workflow."""
+
+    directory: Path
+    project_name: str | None = None
+    python_version: str = "3.8.10"
+    loader_type: str = "console"
+    entry_suffix: str = ".ent"
+    generate_loader: bool = True
+    recursive: bool = False
+    offline: bool = False
+    max_concurrent: int = 4
+    debug: bool = False
+    cache_dir: Path | None = None
+    archive_format: str = "zip"
+    mirror: str = "aliyun"
+
+
+@dataclass
+class ParseProjectResult:
+    """Result from project parsing task."""
+
+    projects: dict[str, Any]
+    projects_file: str
+
+
+@dataclass
+class PackSourceResult:
+    """Result from source packing task."""
+
+    packed_projects: list[str]
+    output_dir: str
+
+
+@dataclass
+class InstallPythonResult:
+    """Result from Python installation task."""
+
+    version: str
+    target_dir: str
+    install_result: Any
+
+
+@dataclass
+class PackLibrariesResult:
+    """Result from library packing task."""
+
+    pack_result: Any
+    packages_dir: str
+
+
+class ParseProjectTask(IOTask):
+    """Task to parse project configuration using pyprojectparse."""
+
+    def __init__(self, directory: Path, recursive: bool = False, timeout: float = 60.0):
+        super().__init__("parse_project", 2.0, [], timeout)
+        self.directory = directory
+        self.recursive = recursive
+
+    async def execute(self, context: dict[str, Any]) -> Any:
+        """Execute project parsing."""
+        logger.info(f"Starting project parsing: {self.directory}")
+
+        try:
+            projects = Solution.from_directory(
+                root_dir=self.directory, recursive=self.recursive
+            )
+
+            logger.info(f"Found {len(projects)} project(s)")
+            for project in projects.values():
+                logger.info(project)
+
+            return {
+                "projects": projects,
+                "projects_file": str(self.directory / "projects.json"),
+            }
+
+        except Exception as e:
+            logger.error(f"Failed to parse projects: {e}")
+            raise
+
+
+class PackSourceTask(IOTask):
+    """Task to pack source code using pysourcepack."""
+
+    def __init__(
+        self,
+        directory: Path,
+        projects_file: Path,
+        project_name: str | None = None,
+        timeout: float = 120.0,
+    ):
+        super().__init__("pack_source", 5.0, ["parse_project"], timeout)
+        self.base_dir = directory
+        self.projects_file = projects_file
+        self.projects: dict[str, Project] = {}
+        self.project_name = project_name
+
+    def _pack_projects(self, projects: dict) -> list[str]:
+        """Pack specified projects.
+
+        Args:
+            projects: Projects data dict
+
+        Returns:
+            List of packed project names
+        """
+        project_names = (
+            [self.project_name] if self.project_name else list(projects.keys())
+        )
+        packed_projects = []
+
+        for name in project_names:
+            logger.info(f"Packing project: {name}")
+            pack_project(base_dir=self.base_dir, project_name=name, projects=projects)
+            packed_projects.append(name)
+
+        return packed_projects
+
+    async def execute(self, context: dict[str, Any]) -> Any:
+        """Execute source packing."""
+        logger.info(f"Starting source packing: {self.base_dir}")
+
+        try:
+            projects = Solution.from_directory(
+                root_dir=self.base_dir, recursive=True, update=False
+            ).projects
+
+            packed_projects = self._pack_projects(projects)
+            logger.info(f"Packed {len(packed_projects)} project(s)")
+            return {"packed_projects": packed_projects, "output_dir": "dist/src"}
+
+        except Exception as e:
+            logger.error(f"Failed to pack source: {e}")
+            raise
+
+
+class InstallPythonTask(IOTask):
+    """Task to install embedded Python using pyembedinstall."""
+
+    def __init__(
+        self,
+        version: str,
+        target_dir: Path,
+        offline: bool = False,
+        timeout: float = 300.0,
+    ):
+        super().__init__("install_python", 10.0, ["parse_project"], timeout)
+        self.version = version
+        self.target_dir = target_dir
+        self.offline = offline
+
+    def _get_architecture(self) -> str:
+        """Determine system architecture.
+
+        Returns:
+            Architecture string (amd64 or arm64)
+        """
+        arch = platform.machine().lower()
+        if arch in ("amd64", "x86_64"):
+            return "amd64"
+        elif arch in ("arm64", "aarch64"):
+            return "arm64"
+        return "amd64"
+
+    def _prepare_cache_dir(self) -> Path:
+        """Prepare cache directory for Python installation.
+
+        Returns:
+            Cache directory path
+        """
+        from sfi.pyembedinstall.pyembedinstall import _DEFAULT_CACHE_DIR
+
+        cache_dir = _DEFAULT_CACHE_DIR
+        cache_dir.mkdir(parents=True, exist_ok=True)
+        return cache_dir
+
+    def _install_python(self, cache_dir: Path, arch: str) -> Any:
+        """Install embedded Python.
+
+        Args:
+            cache_dir: Cache directory path
+            arch: System architecture
+
+        Returns:
+            Installation result
+        """
+        from sfi.pyembedinstall.pyembedinstall import (
+            EmbedInstallConfig,
+            install_embed_python,
+        )
+
+        config = EmbedInstallConfig(
+            target_dir=self.target_dir,
+            version=self.version,
+            cache_dir=cache_dir,
+            offline=self.offline,
+            keep_cache=True,
+            skip_speed_test=False,
+            arch=arch,
+        )
+
+        return install_embed_python(config)
+
+    async def execute(self, context: dict[str, Any]) -> Any:
+        """Execute Python installation."""
+        logger.info(f"Starting Python installation: {self.version}")
+
+        try:
+            cache_dir = self._prepare_cache_dir()
+            arch = self._get_architecture()
+            install_result = self._install_python(cache_dir, arch)
+
+            logger.info(f"Python {self.version} installed to {self.target_dir}")
+
+            return {
+                "version": self.version,
+                "target_dir": str(self.target_dir),
+                "install_result": install_result,
+            }
+
+        except Exception as e:
+            logger.error(f"Failed to install Python: {e}")
+            raise
+
+
+class PackLibrariesTask(IOTask):
+    """Task to pack dependencies using pylibpack."""
+
+    def __init__(
+        self,
+        project_dir: Path,
+        output_dir: Path,
+        cache_dir: Path | None = None,
+        python_version: str | None = None,
+        max_workers: int = 4,
+        archive_format: str = "zip",
+        mirror: str = "aliyun",
+        timeout: float = 300.0,
+    ):
+        super().__init__("pack_libraries", 10.0, ["parse_project"], timeout)
+        self.project_dir = project_dir
+        self.output_dir = output_dir
+        self.cache_dir = cache_dir
+        self.python_version = python_version
+        self.max_workers = max_workers
+        self.archive_format = archive_format
+        self.mirror = mirror
+
+    def _create_packer(self) -> Any:
+        """Create PyLibPack instance.
+
+        Returns:
+            PyLibPack instance
+        """
+        from sfi.pylibpack.pylibpack import PyLibPack
+
+        return PyLibPack(
+            cache_dir=self.cache_dir,
+            python_version=self.python_version,
+            mirror=self.mirror,
+        )
+
+    async def execute(self, context: dict[str, Any]) -> Any:
+        """Execute library packing."""
+        logger.info(f"Starting library packing: {self.project_dir}")
+
+        try:
+            packer = self._create_packer()
+            pack_result = packer.pack(
+                base_dir=self.project_dir,
+                output_dir=self.output_dir,
+                max_workers=self.max_workers,
+            )
+
+            logger.info(
+                f"Library packing completed: {pack_result.successful}/{pack_result.total}"
+            )
+
+            return {
+                "pack_result": pack_result,
+                "packages_dir": pack_result.output_dir,
+            }
+
+        except Exception as e:
+            logger.error(f"Failed to pack libraries: {e}")
+            raise
+
+
+class GenerateLoaderTask(CPUTask):
+    """Task to generate loader using pyloadergen."""
+
+    def __init__(
+        self,
+        base_dir: Path,
+        debug: bool = False,
+        timeout: float = 60.0,
+    ):
+        super().__init__(
+            "generate_loader", 100000, ["parse_project", "pack_source"], timeout
+        )
+        self.base_dir = base_dir
+        self.debug = debug
+
+    async def execute(self, inputs: dict[str, Any]) -> Any:
+        """Execute loader generation."""
+        try:
+            from sfi.pyloadergen.pyloadergen import generate_loader
+
+            generate_loader(self.base_dir, self.debug)
+        except Exception as e:
+            logger.error(f"Failed to generate loader: {e}")
+            raise
+
+
+class AssemblePackageTask(SerialTask):
+    """Task to assemble final package."""
+
+    def __init__(
+        self, output_dir: Path, dependencies: list[str], timeout: float = 60.0
+    ):
+        self.output_dir = output_dir
+        super().__init__("assemble_package", self._assemble, dependencies, timeout)
+
+    def _get_project_dir(self, inputs: dict[str, Any]) -> Path:
+        """Get project directory from parse result or current directory."""
+        if "parse_project" in inputs and hasattr(inputs["parse_project"], "data"):
+            parse_result = inputs["parse_project"].data
+            if isinstance(parse_result, dict) and "projects_file" in parse_result:
+                return Path(parse_result["projects_file"]).parent
+        return Path.cwd()
+
+    def _prepare_dist_dir(self) -> Path:
+        """Prepare and return distribution directory."""
+        dist_dir = (
+            self.output_dir.parent if self.output_dir.is_file() else self.output_dir
+        )
+        dist_dir = dist_dir if dist_dir.name == "dist" else dist_dir.parent / "dist"
+        dist_dir.mkdir(parents=True, exist_ok=True)
+        return dist_dir
+
+    def _copy_loaders(self, project_dir: Path, dist_dir: Path) -> int:
+        """Copy loaders and entry files to dist directory."""
+        loader_dir = project_dir / "dist"
+        if not loader_dir.exists():
+            return 0
+
+        loaders_count = 0
+        for loader in loader_dir.glob("*.ent"):
+            logger.info(f"Entry file: {loader.name}")
+            loaders_count += 1
+
+        # Support both Linux (no extension) and Windows (.exe) executables
+        for loader in loader_dir.glob("*.exe"):
+            logger.info(f"Executable: {loader.name}")
+            shutil.copy2(loader, dist_dir / loader.name)
+            loaders_count += 1
+
+        # Also copy Linux executables (files without extension)
+        for loader in loader_dir.glob("*"):
+            if loader.is_file() and not loader.name.endswith((".ent", ".exe")):
+                logger.info(f"Executable: {loader.name}")
+                shutil.copy2(loader, dist_dir / loader.name)
+                loaders_count += 1
+
+        logger.info(f"Found and copied {loaders_count} loader(s) and entry file(s)")
+        return loaders_count
+
+    def _copy_libraries(self, project_dir: Path, dist_dir: Path) -> None:
+        """Copy libraries to dist/site-packages directory."""
+        libs_dir = project_dir / "dist" / "libs"
+        if not libs_dir.exists():
+            return
+
+        dest_libs_dir = dist_dir / "site-packages"
+        if dest_libs_dir.exists():
+            shutil.rmtree(dest_libs_dir)
+        shutil.copytree(libs_dir, dest_libs_dir)
+        logger.info(f"Libraries copied to {dest_libs_dir}")
+
+    def _create_metadata(self, dist_dir: Path) -> dict[str, Any]:
+        """Create package metadata file."""
+        metadata = {
+            "version": __version__,
+            "build": __build__,
+            "assembled_at": asyncio.get_event_loop().time(),
+        }
+
+        metadata_file = dist_dir / "metadata.json"
+        with open(metadata_file, "w", encoding="utf-8") as f:
+            json.dump(metadata, f, indent=2)
+
+        return metadata
+
+    def _assemble(
+        self, inputs: dict[str, Any], state: dict[str, Any]
+    ) -> dict[str, Any]:
+        """Assemble final package."""
+        logger.info("Starting package assembly")
+
+        try:
+            project_dir = self._get_project_dir(inputs)
+            dist_dir = self._prepare_dist_dir()
+
+            self._copy_loaders(project_dir, dist_dir)
+            self._copy_libraries(project_dir, dist_dir)
+            metadata = self._create_metadata(dist_dir)
+
+            logger.info(f"Package assembled: {dist_dir}")
+            return {"output_dir": str(dist_dir), "metadata": metadata}
+
+        except Exception as e:
+            logger.error(f"Failed to assemble package: {e}")
+            raise
+
+
+class PackageWorkflow:
+    """Package workflow orchestrator."""
+
+    def __init__(self, directory: Path, config: WorkflowConfig):
+        self.directory = directory
+        self.config = config
+        self.engine = WorkflowEngine(max_concurrent=config.max_concurrent)
+
+    def _add_parse_task(self) -> None:
+        """Add project parsing task to workflow."""
+        parse_task = ParseProjectTask(
+            directory=self.directory,
+            recursive=self.config.recursive,
+        )
+        self.engine.add_task(parse_task)
+
+    def _add_pack_and_install_tasks(self) -> None:
+        """Add pack source and install Python tasks to workflow."""
+        pack_task = PackSourceTask(
+            directory=self.directory,
+            projects_file=self.directory / "projects.json",
+            project_name=self.config.project_name,
+        )
+        self.engine.add_task(pack_task)
+
+        install_task = InstallPythonTask(
+            version=self.config.python_version,
+            target_dir=self.directory / "dist" / "runtime",
+            offline=self.config.offline,
+        )
+        self.engine.add_task(install_task)
+
+    def _add_pack_libraries_task(self) -> None:
+        """Add library packing task to workflow."""
+        lib_pack_task = PackLibrariesTask(
+            project_dir=self.directory,
+            output_dir=self.directory / "dist/site-packages",
+            cache_dir=self.config.cache_dir,
+            python_version=self.config.python_version,
+            max_workers=self.config.max_concurrent,
+            archive_format=self.config.archive_format,
+            mirror=self.config.mirror,
+        )
+        self.engine.add_task(lib_pack_task)
+
+    def _add_loader_task(self) -> list[str]:
+        """Add loader generation task to workflow.
+
+        Returns:
+            List of task dependencies for assembly phase
+        """
+        if not self.config.generate_loader:
+            return ["pack_source", "install_python"]
+
+        loader_task = GenerateLoaderTask(self.directory, self.config.debug)
+        self.engine.add_task(loader_task)
+
+        assembly_deps = ["pack_source", "install_python", "generate_loader"]
+        assembly_deps.append("pack_libraries")
+
+        return assembly_deps
+
+    def _add_assemble_task(self, dependencies: list[str]) -> None:
+        """Add package assembly task to workflow.
+
+        Args:
+            dependencies: List of task dependencies
+        """
+        assemble_task = AssemblePackageTask(
+            output_dir=self.directory / "dist",
+            dependencies=dependencies,
+        )
+        self.engine.add_task(assemble_task)
+
+    def build_workflow(self) -> WorkflowEngine:
+        """Build the packaging workflow."""
+        logger.info("Building packaging workflow")
+
+        self._add_parse_task()
+        self._add_pack_and_install_tasks()
+        self._add_pack_libraries_task()
+        dependencies = self._add_loader_task()
+        self._add_assemble_task(dependencies)
+
+        return self.engine
+
+    def _log_execution_summary(self, summary: dict[str, Any]) -> None:
+        """Log workflow execution summary.
+
+        Args:
+            summary: Execution summary dict
+        """
+        logger.info("=" * 50)
+        logger.info("Workflow execution summary:")
+        logger.info(f"  Total tasks: {summary['total_tasks']}")
+        logger.info(f"  Completed: {summary['completed']}")
+        logger.info(f"  Failed: {summary['failed']}")
+        logger.info(f"  Success rate: {summary['success_rate'] * 100:.1f}%")
+        logger.info(f"  Total time: {summary['total_execution_time']:.2f}s")
+        logger.info("=" * 50)
+
+    async def execute(self) -> dict[str, Any]:
+        """Execute the packaging workflow.
+
+        Returns:
+            Dict with results and summary
+        """
+        logger.info("Starting packaging workflow execution")
+
+        self.build_workflow()
+
+        try:
+            results = await self.engine.execute_workflow()
+            summary = self.engine.get_execution_summary()
+            self._log_execution_summary(summary)
+
+            return {"results": results, "summary": summary}
+
+        except Exception as e:
+            logger.error(f"Workflow execution failed: {e}")
+            raise
+
+
+def _load_projects_data(directory: Path, silent: bool = False) -> dict[str, Any] | None:
+    """Load projects data from projects.json.
+
+    Args:
+        directory: Project directory containing projects.json
+        silent: If True, use warning instead of error messages
+
+    Returns:
+        Projects data dict or None if not found/error
+    """
+    projects_file = directory / "projects.json"
+
+    if not projects_file.exists():
+        level = logger.warning if silent else logger.error
+        level(f"No projects.json found in {directory}")
+        logger.info("Run 'pypack build' first to create projects.json")
+        return None
+
+    try:
+        with open(projects_file, encoding="utf-8") as f:
+            projects_data = json.load(f)
+
+        if not projects_data:
+            level = logger.info if silent else logger.error
+            level("No projects found in projects.json")
+            return None
+
+        return projects_data
+    except Exception as e:
+        logger.error(f"Failed to load projects.json: {e}")
+        return None
+
+
+def _get_project_info(project_info: Any) -> tuple[str, str, str]:
+    """Extract project info from project data.
+
+    Args:
+        project_info: Project info dict or string
+
+    Returns:
+        Tuple of (version, entry, description)
+    """
+    if isinstance(project_info, str):
+        return "N/A", "N/A", ""
+
+    version = (
+        project_info.get("version", "N/A") if isinstance(project_info, dict) else "N/A"
+    )
+    entry = "main.py"
+    description = (
+        project_info.get("description", "") if isinstance(project_info, dict) else ""
+    )
+    return version, entry, description
+
+
+def _print_project(project_name: str, project_info: Any, index: int) -> None:
+    """Print project information.
+
+    Args:
+        project_name: Name of the project
+        project_info: Project info dict or string
+        index: Index number for listing
+    """
+    version, entry, description = _get_project_info(project_info)
+
+    logger.info(f"\n[{index}] {project_name}")
+    logger.info(f"    Version: {version}")
+    logger.info(f"    Entry: {entry}")
+    if description:
+        logger.info(f"    Description: {description}")
+
+
+def list_projects(directory: Path) -> None:
+    """List projects from projects.json.
+
+    Args:
+        directory: Project directory containing projects.json
+    """
+    projects_data = _load_projects_data(directory, silent=True)
+
+    if not projects_data:
+        return
+
+    logger.info(f"Found {len(projects_data)} project(s):")
+    logger.info("=" * 60)
+
+    for i, (project_name, project_info) in enumerate(projects_data.items(), 1):
+        _print_project(project_name, project_info, i)
+
+    logger.info("=" * 60)
+
+
+def _get_available_executables(directory: Path) -> list[str]:
+    """Get list of available executables in dist directory.
+
+    Args:
+        directory: Project directory
+
+    Returns:
+        List of executable names (without .exe extension)
+    """
+    dist_dir = directory / "dist"
+    if not dist_dir.exists():
+        logger.error(f"Dist directory not found: {dist_dir}")
+        logger.info("Run 'pypack build' first to build the project")
+        return []
+
+    # Support both Windows (.exe) and Linux (no extension) executables
+    exe_names = set()
+    for exe in dist_dir.glob("*.exe"):
+        if exe.is_file():
+            exe_names.add(exe.stem)
+
+    for exe in dist_dir.glob("*"):
+        if exe.is_file() and not exe.name.endswith((".ent", ".exe", ".json")):
+            exe_names.add(exe.name)
+
+    available_exes = list(exe_names)
+    if not available_exes:
+        logger.error("No executables found in dist directory")
+        logger.info("Run 'pypack build' first to build the project")
+
+    return available_exes
+
+
+def _find_matching_executables(
+    project_name: str, available_exes: list[str]
+) -> list[str]:
+    """Find executables matching project name.
+
+    Args:
+        project_name: Project name to match
+        available_exes: List of available executable names
+
+    Returns:
+        List of matching executable names
+    """
+    return [
+        exe
+        for exe in available_exes
+        if exe == project_name or exe.startswith(f"{project_name}-")
+    ]
+
+
+def _log_available_executables(available_exes: list[str]) -> None:
+    """Log available executable names.
+
+    Args:
+        available_exes: List of available executable names
+    """
+    logger.info("Available executables:")
+    for exe in available_exes:
+        logger.info(f"** {exe} **")
+
+
+def _resolve_exact_project_name(
+    project_name: str, available_exes: list[str]
+) -> str | None:
+    """Resolve executable when project name is specified.
+
+    Args:
+        project_name: Project name to resolve
+        available_exes: List of available executable names
+
+    Returns:
+        Target executable name or None
+    """
+    if project_name in available_exes:
+        return project_name
+    return None
+
+
+def _resolve_project_by_name(
+    project_name: str, available_exes: list[str]
+) -> str | None:
+    """Resolve executable by matching project name.
+
+    Args:
+        project_name: Project name to resolve
+        available_exes: List of available executable names
+
+    Returns:
+        Target executable name or None
+    """
+    matching_exes = _find_matching_executables(project_name, available_exes)
+
+    if len(matching_exes) == 1:
+        return matching_exes[0]
+    elif len(matching_exes) > 1:
+        logger.error(f"Multiple executables found for project '{project_name}':")
+        for exe in matching_exes:
+            logger.info(f"  - {exe}")
+        logger.info("Please specify the full executable name (e.g., 'docscan-gui')")
+        return None
+
+    logger.error(f"No executable found for project '{project_name}'")
+    return None
+
+
+def _resolve_no_project_name(available_exes: list[str]) -> str | None:
+    """Resolve executable when no project name is specified.
+
+    Args:
+        available_exes: List of available executable names
+
+    Returns:
+        Target executable name or None
+    """
+    if len(available_exes) == 1:
+        logger.info(f"Running single executable: {available_exes[0]}")
+        return available_exes[0]
+
+    logger.error(
+        "Multiple executables found. Please specify executable name with --project"
+    )
+    _log_available_executables(available_exes)
+    return None
+
+
+def _resolve_target_executable(
+    project_name: str | None,
+    available_exes: list[str],
+    projects_data: dict[str, Any],
+) -> str | None:
+    """Resolve which executable to run based on project name.
+
+    Args:
+        project_name: Project or executable name to run
+        available_exes: List of available executable names
+        projects_data: Projects data dict
+
+    Returns:
+        Target executable name or None if not found/ambiguous
+    """
+    if not project_name:
+        return _resolve_no_project_name(available_exes)
+
+    exact_match = _resolve_exact_project_name(project_name, available_exes)
+    if exact_match:
+        return exact_match
+
+    if project_name in projects_data:
+        return _resolve_project_by_name(project_name, available_exes)
+
+    logger.error(f"Project or executable '{project_name}' not found")
+    _log_available_executables(available_exes)
+    return None
+
+
+def _execute_project(exe_path: Path, dist_dir: Path) -> None:
+    """Execute the project executable.
+
+    Args:
+        exe_path: Path to the executable
+        dist_dir: Working directory for execution
+    """
+    import subprocess
+
+    try:
+        subprocess.run([str(exe_path)], cwd=str(dist_dir), check=True)
+    except subprocess.CalledProcessError as e:
+        logger.error(f"Project execution failed with exit code {e.returncode}")
+    except KeyboardInterrupt:
+        logger.info("Project execution interrupted")
+    except FileNotFoundError:
+        logger.error(f"Failed to execute {exe_path}")
+
+
+def run_project(project_name: str | None, directory: Path) -> None:
+    """Run a built project.
+
+    Args:
+        project_name: Project name or executable name to run (e.g., 'docscan' or 'docscan-gui')
+        directory: Project directory
+    """
+    projects_data = _load_projects_data(directory)
+    if not projects_data:
+        return
+
+    available_exes = _get_available_executables(directory)
+    if not available_exes:
+        return
+
+    target_exe_name = _resolve_target_executable(
+        project_name, available_exes, projects_data
+    )
+    if not target_exe_name:
+        return
+
+    # Try both Windows (.exe) and Linux (no extension) executables
+    exe_path_with_ext = directory / "dist" / f"{target_exe_name}.exe"
+    exe_path_no_ext = directory / "dist" / target_exe_name
+
+    exe_path = None
+    if exe_path_with_ext.exists():
+        exe_path = exe_path_with_ext
+    elif exe_path_no_ext.exists():
+        exe_path = exe_path_no_ext
+
+    if not exe_path:
+        logger.error(f"Executable not found for '{target_exe_name}'")
+        logger.info("Run 'pypack build' first to build the project")
+        return
+
+    logger.info(f"Starting: {target_exe_name}")
+    logger.info(f"Executable: {exe_path}")
+    _execute_project(exe_path, directory / "dist")
+
+
+def clean_project(directory: Path) -> None:
+    """Clean build artifacts and package files.
+
+    Args:
+        directory: Project directory to clean
+    """
+    logger.info("Cleaning build artifacts...")
+
+    cleaned_dirs, cleaned_files = _clean_build_artifacts(directory)
+
+    if not cleaned_dirs and not cleaned_files:
+        logger.info("No build artifacts found")
+    else:
+        logger.info(
+            f"Cleaned {len(cleaned_dirs)} directories and {len(cleaned_files)} file(s)"
+        )
+
+
+def _should_clean(entry: Path) -> bool:
+    """Check if a directory or file should be cleaned.
+
+    Args:
+        entry: Path to check
+
+    Returns:
+        True if the entry should be cleaned
+    """
+    protected_dirs = {
+        ".git",
+        ".venv",
+        ".virtualenv",
+        ".vscode",
+        ".idea",
+        ".codebuddy",
+        ".qoder",
+    }
+
+    if entry.is_file() and entry.name == "projects.json":
+        return True
+
+    if not entry.is_dir():
+        return False
+
+    if entry.name.startswith(".") and entry.name in protected_dirs:
+        return False
+
+    return (
+        entry.name.startswith(".")
+        or entry.name.startswith("__")
+        or entry.name in ("build", "dist", "pysfi_build", "cbuild", "benchmarks")
+    )
+
+
+def _clean_build_artifacts(directory: Path) -> tuple[list[str], list[str]]:
+    """Clean all build artifacts from directory.
+
+    Args:
+        directory: Project directory to clean
+
+    Returns:
+        Tuple of (cleaned directories, cleaned files)
+    """
+    cleaned_dirs = []
+    cleaned_files = []
+
+    entries_to_clean = [f for f in directory.iterdir() if _should_clean(f)]
+
+    for entry in entries_to_clean:
+        if not entry.exists():
+            continue
+
+        if entry.is_dir():
+            logger.info(f"Removing directory: {entry}")
+            if _remove_directory(entry):
+                cleaned_dirs.append(str(entry))
+                logger.info(f"  Removed directory: {entry}")
+            else:
+                logger.warning(f"  Failed to remove {entry}")
+        elif entry.is_file():
+            logger.info(f"Removing file: {entry}")
+            if _remove_file(entry):
+                cleaned_files.append(str(entry))
+                logger.info(f"  Removed file: {entry}")
+            else:
+                logger.warning(f"  Failed to remove {entry}")
+
+    return cleaned_dirs, cleaned_files
+
+
+def _remove_directory(dir_path: Path) -> bool:
+    """Remove a directory safely.
+
+    Args:
+        dir_path: Directory path to remove
+
+    Returns:
+        True if removal succeeded
+    """
+    try:
+        shutil.rmtree(dir_path)
+        return True
+    except Exception:
+        return False
+
+
+def _remove_file(file_path: Path) -> bool:
+    """Remove a file safely.
+
+    Args:
+        file_path: File path to remove
+
+    Returns:
+        True if removal succeeded
+    """
+    try:
+        file_path.unlink()
+        return True
+    except Exception:
+        return False
+
+
+def parse_args() -> argparse.Namespace:
+    """Parse command line arguments.
+
+    Returns:
+        Parsed arguments namespace
+    """
+    parser = argparse.ArgumentParser(
+        prog="pypack", description="Python packaging tool with workflow orchestration"
+    )
+
+    parser.add_argument(
+        "action",
+        choices=("build", "b", "list", "l", "run", "r", "clean", "c", "version", "v"),
+        help="Action to perform",
+    )
+    parser.add_argument(
+        "project",
+        type=str,
+        nargs="?",
+        default=None,
+        help="Project or executable name (e.g., 'docscan' or 'docscan-gui')",
+    )
+    parser.add_argument("--debug", "-d", action="store_true", help="Debug mode")
+    parser.add_argument(
+        "--python-version", type=str, default="3.8.10", help="Python version to install"
+    )
+    parser.add_argument(
+        "--loader-type",
+        type=str,
+        choices=("console", "gui"),
+        default="console",
+        help="Loader type",
+    )
+    parser.add_argument(
+        "--entry-suffix",
+        type=str,
+        default=".ent",
+        help="Entry file suffix (default: .ent, alternatives: .py)",
+    )
+    parser.add_argument(
+        "--no-loader", action="store_true", help="Skip loader generation"
+    )
+    parser.add_argument(
+        "-r", "--recursive", action="store_true", help="Parse projects recursively"
+    )
+    parser.add_argument("-o", "--offline", action="store_true", help="Offline mode")
+    parser.add_argument(
+        "-j", "--jobs", type=int, default=4, help="Maximum concurrent tasks"
+    )
+
+    # Library packing arguments
+    parser.add_argument(
+        "--cache-dir",
+        type=str,
+        default=None,
+        help="Custom cache directory for dependencies",
+    )
+    parser.add_argument(
+        "--archive-format",
+        type=str,
+        choices=("zip", "7z", "nsis"),
+        default="zip",
+        help="Archive format for dependencies",
+    )
+    parser.add_argument(
+        "--mirror",
+        type=str,
+        default="aliyun",
+        choices=("pypi", "tsinghua", "aliyun", "ustc", "douban", "tencent"),
+        help="PyPI mirror source for faster downloads",
+    )
+
+    return parser.parse_args()
+
+
+async def _execute_build_workflow(config: WorkflowConfig) -> None:
+    """Execute the build workflow."""
+    workflow = PackageWorkflow(directory=config.directory, config=config)
+
+    try:
+        await workflow.execute()
+        logger.info("Packaging completed successfully!")
+    except Exception as e:
+        logger.error(f"Packaging failed: {e}")
+        raise
+
+
+def main() -> None:
+    """Main entry point for package workflow tool."""
+    args = parse_args()
+
+    if args.debug:
+        logging.getLogger().setLevel(logging.DEBUG)
+
+    if args.action in {"version", "v"}:
+        logger.info(f"pypack {__version__} (build {__build__})")
+        return
+
+    if args.action in {"list", "l"}:
+        list_projects(cwd)
+        return
+
+    if args.action in {"run", "r"}:
+        run_project(args.project, cwd)
+        return
+
+    if args.action in {"clean", "c"}:
+        clean_project(cwd)
+        return
+
+    cache_dir = Path(args.cache_dir) if args.cache_dir else None
+    config = WorkflowConfig(
+        directory=cwd,
+        project_name=args.project,
+        python_version=args.python_version,
+        loader_type=args.loader_type,
+        entry_suffix=args.entry_suffix,
+        generate_loader=not args.no_loader,
+        recursive=args.recursive,
+        offline=args.offline,
+        max_concurrent=args.jobs,
+        debug=args.debug,
+        cache_dir=cache_dir,
+        archive_format=args.archive_format,
+        mirror=args.mirror,
+    )
+
+    asyncio.run(_execute_build_workflow(config))
+
+
+if __name__ == "__main__":
+    main()