bootstack 0.1.0a1__py3-none-any.whl

bootstack/cli/doctor.py

@@ -0,0 +1,195 @@
+"""bootstack doctor command - Validate project structure and environment."""
+
+from __future__ import annotations
+
+import argparse
+import platform
+import sys
+from pathlib import Path
+
+from bootstack.cli.config import TtkbConfig, find_config
+
+
+_OK = "  [OK]   "
+_WARN = "  [WARN] "
+_FAIL = "  [FAIL] "
+
+
+def add_parser(subparsers: argparse._SubParsersAction) -> None:
+    """Add the 'doctor' subcommand parser."""
+    parser = subparsers.add_parser(
+        "doctor",
+        help="Diagnose project and environment health",
+        description=(
+            "Validate bootstack.toml, check the project layout, and report "
+            "environment versions relevant to building and running."
+        ),
+    )
+    parser.set_defaults(func=run_doctor)
+
+
+def run_doctor(args: argparse.Namespace) -> None:
+    """Run the diagnostic checks."""
+    failures = 0
+    warnings = 0
+
+    # ---- Environment -------------------------------------------------------
+    print("Environment:")
+    print(f"{_OK}Python {platform.python_version()} ({sys.executable})")
+
+    tk_version, tk_error = _probe_tk()
+    if tk_version:
+        print(f"{_OK}Tcl/Tk {tk_version}")
+    else:
+        print(f"{_FAIL}Tcl/Tk: {tk_error}")
+        failures += 1
+
+    ttkb_version = _probe_bootstack()
+    print(f"{_OK}bootstack {ttkb_version}")
+
+    print()
+
+    # ---- Project -----------------------------------------------------------
+    config_path = find_config()
+    if config_path is None:
+        print("Project:")
+        print(f"{_WARN}No bootstack.toml found in current directory or parents.")
+        print("         (Run 'bootstack start <name>' to create a project, or 'cd' into one.)")
+        return
+
+    project_root = config_path.parent
+    print(f"Project: {project_root}")
+
+    try:
+        config = TtkbConfig.load(config_path)
+    except Exception as e:
+        print(f"{_FAIL}bootstack.toml failed to parse: {e}")
+        sys.exit(1)
+    print(f"{_OK}bootstack.toml parses ([app] name={config.app.name!r}, template={config.app.template!r})")
+
+    # Entry point exists
+    entry_path = project_root / config.app.entry
+    if entry_path.exists():
+        print(f"{_OK}entry point: {config.app.entry}")
+    else:
+        print(f"{_FAIL}entry point missing: {config.app.entry}")
+        failures += 1
+
+    # Layout matches template
+    if entry_path.parts and "src" in entry_path.parts:
+        idx = list(entry_path.parts).index("src")
+        if idx + 1 < len(entry_path.parts):
+            module_dir = project_root.joinpath(*entry_path.parts[: idx + 2])
+            failures += _check_template_layout(config.app.template, module_dir)
+    else:
+        # Non-src layout: skip the views/pages check
+        pass
+
+    # Packaging — always reported. If [build] exists we run the full check;
+    # otherwise we still flag a missing PyInstaller as a heads-up so users
+    # discover it before they reach 'bootstack build'.
+    if config.build is not None:
+        warnings += _check_build(config, project_root)
+    else:
+        warnings += _check_packaging_readiness()
+
+    # ---- Summary -----------------------------------------------------------
+    print()
+    if failures:
+        print(f"{failures} failure(s), {warnings} warning(s).")
+        sys.exit(1)
+    if warnings:
+        print(f"All checks passed with {warnings} warning(s).")
+    else:
+        print("All checks passed.")
+
+
+def _check_template_layout(template: str, module_dir: Path) -> int:
+    """Verify the project's component directory matches its template type.
+
+    Returns the number of failures recorded.
+    """
+    expected = "pages" if template == "appshell" else "views"
+    other = "views" if template == "appshell" else "pages"
+
+    expected_dir = module_dir / expected
+    other_dir = module_dir / other
+
+    failures = 0
+    if expected_dir.exists():
+        print(f"{_OK}layout: found {expected}/ (matches template={template!r})")
+    else:
+        print(f"{_FAIL}layout: expected {expected_dir.relative_to(module_dir.parent.parent)}/ for template={template!r}")
+        failures += 1
+
+    if other_dir.exists():
+        print(f"{_WARN}layout: unexpected {other}/ directory for template={template!r}")
+    return failures
+
+
+def _check_packaging_readiness() -> int:
+    """Report packaging-tool availability for un-promoted projects.
+
+    Never fails — just warns if PyInstaller is missing so users know
+    they have an install ahead of them before 'bootstack build' will work.
+    Returns the number of warnings.
+    """
+    print()
+    print("Packaging (project not yet promoted):")
+    try:
+        import PyInstaller  # noqa: F401
+        print(f"{_OK}PyInstaller is available (run 'bootstack promote --pyinstaller' to enable builds)")
+        return 0
+    except ImportError:
+        print(f"{_WARN}PyInstaller is not installed")
+        print("         Install it before 'bootstack build': pip install pyinstaller")
+        return 1
+
+
+def _check_build(config: TtkbConfig, project_root: Path) -> int:
+    """Verify build-time prerequisites. Returns the number of warnings."""
+    warnings = 0
+    backend = config.build.backend if config.build else None
+    print()
+    print(f"Build (backend={backend!r}):")
+
+    if backend == "pyinstaller":
+        spec = project_root / "build" / "pyinstaller" / "app.spec"
+        if spec.exists():
+            print(f"{_OK}spec file: {spec.relative_to(project_root)}")
+        else:
+            print(f"{_WARN}spec file missing — run 'bootstack promote --pyinstaller --force'")
+            warnings += 1
+        try:
+            import PyInstaller  # noqa: F401
+            print(f"{_OK}PyInstaller is importable")
+        except ImportError:
+            print(f"{_WARN}PyInstaller is not installed (pip install pyinstaller)")
+            warnings += 1
+    else:
+        print(f"{_WARN}unknown build backend: {backend!r}")
+        warnings += 1
+
+    return warnings
+
+
+def _probe_tk() -> tuple[str | None, str | None]:
+    """Return (version, None) on success, (None, error_message) on failure.
+
+    Uses `_tkinter` module constants directly so the probe does not have
+    to instantiate a Tk interpreter (bootstack monkey-patches
+    `Tk.__init__` to require an App, which would trip the probe).
+    """
+    try:
+        import _tkinter
+        return f"{_tkinter.TCL_VERSION} / Tk {_tkinter.TK_VERSION}", None
+    except Exception as e:
+        return None, str(e)
+
+
+def _probe_bootstack() -> str:
+    try:
+        import bootstack
+        return getattr(bootstack, "__version__", "(unknown)")
+    except Exception:
+        return "(import failed)"

bootstack/cli/list_cmd.py

@@ -0,0 +1,71 @@
+"""bootstack list command - List available themes and other resources."""
+
+from __future__ import annotations
+
+import argparse
+import json
+
+
+def add_parser(subparsers: argparse._SubParsersAction) -> None:
+    """Add the 'list' subcommand parser."""
+    parser = subparsers.add_parser(
+        "list",
+        help="List available resources",
+        description="List themes and other available resources.",
+    )
+    list_subparsers = parser.add_subparsers(dest="resource")
+
+    # bootstack list themes
+    themes_parser = list_subparsers.add_parser(
+        "themes",
+        help="List available themes",
+    )
+    themes_parser.set_defaults(func=run_list_themes)
+
+    parser.set_defaults(func=lambda args: parser.print_help())
+
+
+def run_list_themes(args: argparse.Namespace) -> None:
+    """List available themes by reading theme JSON files from the package."""
+    from importlib import resources
+
+    themes: list[dict[str, str]] = []
+
+    for package in ("bootstack.assets.themes",):
+        try:
+            base = resources.files(package)
+        except (ModuleNotFoundError, FileNotFoundError):
+            continue
+        for item in base.iterdir():
+            if not item.name.endswith(".json"):
+                continue
+            try:
+                data = json.loads(item.read_text(encoding="utf-8"))
+                themes.append({
+                    "name": data.get("name", item.name.removesuffix(".json")),
+                    "display_name": data.get("display_name", ""),
+                    "mode": data.get("mode", ""),
+                })
+            except (json.JSONDecodeError, OSError):
+                continue
+
+    if not themes:
+        print("No themes found.")
+        return
+
+    themes.sort(key=lambda t: (t["mode"], t["name"]))
+
+    # Print table
+    name_width = max(max(len(t["name"]) for t in themes), len("Name"))
+    display_width = max(
+        max(len(t["display_name"]) for t in themes), len("Display Name")
+    )
+
+    header = f"  {'Name':<{name_width}}  {'Display Name':<{display_width}}  Mode"
+    print(header)
+    print(f"  {'-' * name_width}  {'-' * display_width}  ----")
+
+    for t in themes:
+        print(f"  {t['name']:<{name_width}}  {t['display_name']:<{display_width}}  {t['mode']}")
+
+    print(f"\n  {len(themes)} themes available.")

bootstack/cli/promote.py

@@ -0,0 +1,120 @@
+"""bootstack promote command - Upgrade project to packaging-ready."""
+
+from __future__ import annotations
+
+import argparse
+from pathlib import Path
+
+from bootstack.cli.config import (
+    BUILD_CONFIG_TEMPLATE,
+    TtkbConfig,
+    find_config,
+)
+from bootstack.cli.pyinstaller import generate_spec
+
+
+def add_parser(subparsers: argparse._SubParsersAction) -> None:
+    """Add the 'promote' subcommand parser."""
+    parser = subparsers.add_parser(
+        "promote",
+        help="Upgrade project to packaging-ready",
+        description="Add build configuration and generate build files for distribution.",
+    )
+    parser.add_argument(
+        "--pyinstaller",
+        action="store_true",
+        help="Enable PyInstaller build support",
+    )
+    parser.add_argument(
+        "--force",
+        action="store_true",
+        help="Overwrite existing build configuration",
+    )
+    parser.set_defaults(func=run_promote)
+
+
+def run_promote(args: argparse.Namespace) -> None:
+    """Execute the promote command."""
+    if not args.pyinstaller:
+        print("Error: Please specify a build backend.")
+        print("  bootstack promote --pyinstaller")
+        return
+
+    # Find project root
+    config_path = find_config()
+    if config_path is None:
+        print("Error: No bootstack.toml found in current directory or parents.")
+        print("Run 'bootstack start <appname>' to create a new project first.")
+        return
+
+    project_root = config_path.parent
+    config = TtkbConfig.load(config_path)
+
+    # Check if already promoted
+    if config.build is not None and not args.force:
+        print("Project already has build configuration.")
+        print("Use --force to overwrite.")
+        return
+
+    print(f"Promoting project '{config.app.name}' for PyInstaller...")
+
+    # Update bootstack.toml with build section
+    _add_build_section(config_path)
+
+    # Create build directory
+    build_dir = project_root / "build" / "pyinstaller"
+    build_dir.mkdir(parents=True, exist_ok=True)
+
+    # Reload config to get build settings
+    config = TtkbConfig.load(config_path)
+
+    # Generate .spec file
+    spec_path = build_dir / "app.spec"
+    generate_spec(config, project_root, spec_path)
+
+    print()
+    print("Project promoted successfully!")
+    print()
+    print("Generated files:")
+    print(f"  - {spec_path.relative_to(project_root)}")
+    print()
+    print("Updated:")
+    print(f"  - bootstack.toml (added [build] section)")
+    print()
+
+    # Warn early if PyInstaller isn't on this interpreter — `bootstack build`
+    # needs it but the promote step itself only writes config.
+    try:
+        import PyInstaller  # noqa: F401
+    except ImportError:
+        print("Note: PyInstaller is not installed in this environment.")
+        print("      Install it before running 'bootstack build':")
+        print("      pip install pyinstaller")
+        print()
+
+    print("Next steps:")
+    print("  1. (Optional) Edit bootstack.toml [build] section")
+    print("  2. Run 'bootstack build' to create executable")
+
+
+def _add_build_section(config_path: Path) -> None:
+    """Add [build] section to existing bootstack.toml."""
+    content = config_path.read_text(encoding="utf-8")
+
+    # Check if [build] section already exists
+    if "[build]" in content:
+        # Remove existing build section and everything after
+        lines = content.split("\n")
+        new_lines = []
+        skip = False
+        for line in lines:
+            if line.strip().startswith("[build"):
+                skip = True
+            if not skip:
+                new_lines.append(line)
+        content = "\n".join(new_lines).rstrip() + "\n"
+
+    # Append build section
+    content += BUILD_CONFIG_TEMPLATE
+
+    config_path.write_text(content, encoding="utf-8")

bootstack/cli/pyinstaller.py

@@ -0,0 +1,246 @@
+"""PyInstaller spec file generation for bootstack projects."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from bootstack.cli.config import TtkbConfig
+
+
+# PyInstaller spec template that reads from bootstack.toml
+SPEC_TEMPLATE = '''\
+# -*- mode: python ; coding: utf-8 -*-
+"""
+PyInstaller spec file for {app_name}.
+
+This file is auto-generated by bootstack CLI.
+Edit bootstack.toml to change build settings, then regenerate with:
+    bootstack promote --pyinstaller --force
+"""
+
+import sys
+from pathlib import Path
+
+# PyInstaller exec's this spec with SPECPATH (directory of the .spec file)
+# in the namespace. __file__ is not defined inside a spec.
+PROJECT_ROOT = Path(SPECPATH).parent.parent
+CONFIG_PATH = PROJECT_ROOT / "bootstack.toml"
+
+# Ensure we can import bootstack CLI tools
+try:
+    from bootstack.cli.config import TtkbConfig
+except ImportError:
+    sys.path.insert(0, str(PROJECT_ROOT / "src"))
+    from bootstack.cli.config import TtkbConfig
+
+if not CONFIG_PATH.exists():
+    raise FileNotFoundError(f"bootstack.toml not found at {{CONFIG_PATH}}")
+
+config = TtkbConfig.load(CONFIG_PATH)
+
+# Extract settings
+APP_NAME = config.app.name
+ENTRY_POINT = PROJECT_ROOT / config.app.entry
+WINDOWED = config.build.windowed if config.build else True
+ONEFILE = config.build.onefile if config.build else False
+
+# Icon handling
+ICON_PATH = None
+if config.build and config.build.icon.path:
+    icon_candidate = PROJECT_ROOT / config.build.icon.path
+    if icon_candidate.exists():
+        ICON_PATH = str(icon_candidate)
+else:
+    # Fall back to the bundled bootstack launch icon (the same artwork
+    # the runtime sets via wm_iconphoto, just rendered as a multi-size
+    # .ico for Windows). Users can override by setting [build.icon] path
+    # in bootstack.toml.
+    try:
+        import bootstack
+        default_icon = Path(bootstack.__file__).parent / "assets" / "bootstack.ico"
+        if default_icon.exists():
+            ICON_PATH = str(default_icon)
+    except Exception:
+        pass
+
+
+# =============================================================================
+# Collect data files
+# =============================================================================
+
+from glob import glob
+
+datas = []
+
+# Always include bootstack.toml
+datas.append((str(CONFIG_PATH), "."))
+
+# Include patterns from config
+if config.build and config.build.datas.include:
+    for pattern in config.build.datas.include:
+        if pattern == "bootstack.toml":
+            continue  # Already added
+        matches = glob(str(PROJECT_ROOT / pattern), recursive=True)
+        for match in matches:
+            match_path = Path(match)
+            if match_path.is_file():
+                rel_path = match_path.relative_to(PROJECT_ROOT)
+                dest_dir = str(rel_path.parent) if rel_path.parent != Path(".") else "."
+                datas.append((str(match_path), dest_dir))
+
+
+# =============================================================================
+# Collect package data (themes, fonts, icon glyphmaps, locales, etc.)
+# =============================================================================
+
+# PyInstaller's collect_data_files walks a package and grabs every non-.py
+# file, returning (src, dest) tuples in the form `datas` expects. We use it
+# here for bootstack's own assets, plus a downstream workaround:
+#
+# WORKAROUND (until upstream fixes ship):
+#   ttkbootstrap_icons ships a complete _pyinstaller/ hook directory, but
+#   its pyproject.toml does not declare the `pyinstaller40` entry point, so
+#   PyInstaller never discovers those hooks. ttkbootstrap_icons_bs also has
+#   no hook of its own. Both manifest at runtime as:
+#       ModuleNotFoundError: No module named 'ttkbootstrap_icons_bs.assets'
+#   We bundle their data files manually here so frozen apps actually work.
+#   Tracked at: https://github.com/israel-dryer/bootstack-icons/issues
+#   Once upstream lands the entry point + a `hook-ttkbootstrap_icons_bs.py`,
+#   the two icon-package entries below can be dropped — PyInstaller will
+#   pick them up automatically.
+from PyInstaller.utils.hooks import collect_data_files
+
+for _pkg in ("bootstack", "ttkbootstrap_icons", "ttkbootstrap_icons_bs"):
+    try:
+        datas += collect_data_files(_pkg)
+    except Exception as _e:  # pragma: no cover
+        print(f"Warning: Could not collect data files from {{_pkg}}: {{_e}}")
+
+
+# =============================================================================
+# Hidden imports for bootstack
+# =============================================================================
+
+hiddenimports = [
+    "bootstack",
+    "bootstack.themes",
+    "bootstack.style",
+    "bootstack.widgets",
+    "ttkbootstrap_icons",
+    "ttkbootstrap_icons_bs",
+    "PIL",
+    "PIL._tkinter_finder",
+    "babel.numbers",
+    "babel.dates",
+    "dateutil",
+    "dateparser",
+]
+
+# babel.bin is a CLI script package whose __init__.py calls exit(1) when
+# imported without args; PyInstaller's binary-dependency analyzer
+# imports it during package walking and crashes. Excluding it is safe
+# because nothing in a bootstack app uses babel's command-line tools.
+excludes = [
+    "babel.bin",
+]
+
+
+# =============================================================================
+# Analysis
+# =============================================================================
+
+a = Analysis(
+    [str(ENTRY_POINT)],
+    pathex=[str(PROJECT_ROOT / "src")],
+    binaries=[],
+    datas=datas,
+    hiddenimports=hiddenimports,
+    hookspath=[],
+    hooksconfig={{}},
+    runtime_hooks=[],
+    excludes=excludes,
+    noarchive=False,
+    optimize=0,
+)
+
+
+# =============================================================================
+# Build
+# =============================================================================
+
+pyz = PYZ(a.pure)
+
+if ONEFILE:
+    exe = EXE(
+        pyz,
+        a.scripts,
+        a.binaries,
+        a.datas,
+        [],
+        name=APP_NAME,
+        debug=False,
+        bootloader_ignore_signals=False,
+        strip=False,
+        upx=True,
+        upx_exclude=[],
+        runtime_tmpdir=None,
+        console=not WINDOWED,
+        disable_windowed_traceback=False,
+        argv_emulation=False,
+        target_arch=None,
+        codesign_identity=None,
+        entitlements_file=None,
+        icon=ICON_PATH,
+    )
+else:
+    exe = EXE(
+        pyz,
+        a.scripts,
+        [],
+        exclude_binaries=True,
+        name=APP_NAME,
+        debug=False,
+        bootloader_ignore_signals=False,
+        strip=False,
+        upx=True,
+        console=not WINDOWED,
+        disable_windowed_traceback=False,
+        argv_emulation=False,
+        target_arch=None,
+        codesign_identity=None,
+        entitlements_file=None,
+        icon=ICON_PATH,
+    )
+
+    coll = COLLECT(
+        exe,
+        a.binaries,
+        a.datas,
+        strip=False,
+        upx=True,
+        upx_exclude=[],
+        name=APP_NAME,
+    )
+'''
+
+
+def generate_spec(
+    config: TtkbConfig,
+    project_root: Path,
+    output_path: Path,
+) -> None:
+    """Generate a PyInstaller spec file.
+
+    Args:
+        config: The project configuration.
+        project_root: Root directory of the project.
+        output_path: Path to write the spec file.
+    """
+    content = SPEC_TEMPLATE.format(
+        app_name=config.app.name,
+    )
+
+    output_path.parent.mkdir(parents=True, exist_ok=True)
+    output_path.write_text(content, encoding="utf-8")