bootstack 0.1.0__py3-none-any.whl

bootstack/cli/dev.py

@@ -0,0 +1,153 @@
+"""bootstack dev command - Run an application with hot reload.
+
+PROVISIONAL — the dev workflow ships in 0.1.0 but is carved out of the API
+freeze and may change in a minor release.
+"""
+
+from __future__ import annotations
+
+import argparse
+import os
+import subprocess
+import sys
+import threading
+from pathlib import Path
+
+from bootstack.cli.config import TtkbConfig, find_config
+
+
+def add_parser(subparsers: argparse._SubParsersAction) -> None:
+    """Add the 'dev' subcommand parser."""
+    parser = subparsers.add_parser(
+        "dev",
+        help="Run the application with hot reload",
+        description=(
+            "Run the application with live reload. Saving a source file updates "
+            "the running app. A module-level `with bs.App()` reloads in place "
+            "(state preserved); anything else falls back to a process restart."
+        ),
+    )
+    parser.add_argument(
+        "path",
+        nargs="?",
+        default=None,
+        help="Path to entry point or directory with bootstack.toml (default: current directory)",
+    )
+    parser.add_argument(
+        "--restart",
+        action="store_true",
+        help="Always reload by restarting the process, even for a module-level app",
+    )
+    parser.set_defaults(func=run_dev)
+
+
+def run_dev(args: argparse.Namespace) -> None:
+    """Execute the dev command."""
+    resolved = _resolve_entry(args.path)
+    if resolved is None:
+        return
+    entry_point, project_root = resolved
+
+    if not entry_point.exists():
+        print(f"Error: Entry point '{entry_point}' does not exist.")
+        return
+
+    try:
+        display_path = entry_point.relative_to(project_root)
+    except ValueError:
+        display_path = entry_point
+    print(f"Starting {display_path} with hot reload...")
+    print("(Save a file to reload. Press Ctrl+C to stop.)")
+    print()
+
+    env = dict(os.environ)
+    env["BOOTSTACK_DEV"] = "1"
+    env["BOOTSTACK_DEV_MODE"] = "restart" if args.restart else "inprocess"
+
+    src_dir = project_root / "src"
+    if src_dir.exists():
+        python_path = env.get("PYTHONPATH", "")
+        env["PYTHONPATH"] = (
+            f"{src_dir}{os.pathsep}{python_path}" if python_path else str(src_dir)
+        )
+
+    # Supervise the app here rather than letting it os.execv itself on restart:
+    # on Windows execv does not replace the process in place — it spawns a new
+    # PID and terminates the caller, which would drop this supervisor after the
+    # first reload and orphan the app. The child re-launches by exiting with
+    # DEV_RESTART_EXIT_CODE; looping subprocess.run is portable and re-establishes
+    # cwd + env on every relaunch.
+    from bootstack.dev._env import DEV_RESTART_EXIT_CODE
+
+    try:
+        while True:
+            result = subprocess.run(
+                [sys.executable, str(entry_point.resolve())],
+                cwd=str(project_root),
+                env=env,
+            )
+            if result.returncode == DEV_RESTART_EXIT_CODE:
+                continue  # a valid edit asked for a clean restart
+            if result.returncode == 0:
+                sys.exit(0)  # the app window was closed normally
+            # The app crashed (e.g. an edit raised at import). Don't end the
+            # session — stay alive and relaunch when the file is fixed and
+            # saved. This is the restart-mode counterpart to the in-process
+            # error banner's fix-and-save recovery; the child's own watcher
+            # died with it, so the supervisor watches in the meantime.
+            print(
+                f"\n[bootstack dev] app exited with code {result.returncode} - "
+                "waiting for a change to retry (Ctrl+C to stop)...",
+                flush=True,
+            )
+            _wait_for_change(str(project_root))
+    except KeyboardInterrupt:
+        print("\nStopped.")
+        sys.exit(0)
+
+
+def _wait_for_change(root: str) -> None:
+    """Block until a watched source file under `root` changes (or Ctrl+C).
+
+    Used by the restart supervisor to stay alive after the app crashes: rather
+    than ending the dev session, it waits for the next save and lets the loop
+    relaunch.
+    """
+    from bootstack.dev._watcher import PollWatcher
+
+    changed = threading.Event()
+    watcher = PollWatcher(root, lambda _paths: changed.set())
+    watcher.start()
+    try:
+        # Short timed waits keep Ctrl+C responsive on Windows, where a bare
+        # Event.wait() with no timeout can swallow the interrupt.
+        while not changed.wait(0.3):
+            pass
+    finally:
+        watcher.stop()
+
+
+def _resolve_entry(path: str | None) -> tuple[Path, Path] | None:
+    """Resolve (entry_point, project_root) from a path or bootstack.toml."""
+    if path:
+        p = Path(path)
+        if p.is_file() and p.suffix == ".py":
+            return p, p.parent
+        if p.is_dir():
+            config_path = p / "bootstack.toml"
+            if not config_path.exists():
+                print(f"Error: No bootstack.toml found in '{p}'")
+                return None
+            config = TtkbConfig.load(config_path)
+            return p / config.app.entry, p
+        print(f"Error: '{path}' is not a valid file or directory")
+        return None
+
+    config_path = find_config()
+    if config_path is None:
+        print("Error: No bootstack.toml found in current directory or parents.")
+        print("Pass a path: bootstack dev app.py")
+        return None
+    config = TtkbConfig.load(config_path)
+    project_root = config_path.parent
+    return project_root / config.app.entry, project_root

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/icons.py

@@ -0,0 +1,98 @@
+"""Icons command — launches the Bootstrap Icons browser."""
+from __future__ import annotations
+
+import argparse
+
+
+def add_parser(subparsers: argparse._SubParsersAction) -> None:
+    parser = subparsers.add_parser(
+        "icons",
+        help="Browse Bootstrap Icons available in bootstack",
+        description=(
+            "Launch the Bootstrap Icons browser.\n\n"
+            "Displays all Bootstrap Icons bundled with bootstack. "
+            "Click any icon to copy its name to the clipboard — the "
+            "copied name works directly as icon= on any bootstack widget."
+        ),
+    )
+    parser.set_defaults(func=lambda args: run_icons())
+
+
+_DEFAULT_STATUS = (
+    'Click an icon to copy its name  ·  use as  icon="name"  on any widget'
+)
+
+
+def run_icons() -> None:
+    import bootstack as bs
+    from bootstack.clipboard import set_clipboard
+    from bootstack.data import MemoryDataSource, col
+    from bootstack.images import get_icon, list_icons
+
+    names = list_icons()
+
+    with bs.App(title="Bootstrap Icons", size=(990, 720), gap=0) as app:
+        # Each record carries a theme-following Image. Gallery recycles its tiles,
+        # so the thumbnails render lazily as they scroll into view and recolor
+        # with the theme on their own — no manual batching or repaint needed.
+        records = [
+            {"id": i, "name": name, "icon": get_icon(name, size=32)}
+            for i, name in enumerate(names)
+        ]
+        source = MemoryDataSource()
+        source.load(records)
+
+        count = bs.Signal("")
+        status = bs.Signal(_DEFAULT_STATUS)
+
+        def update_count() -> None:
+            count.set(f"{source.count:,} of {len(names):,} icons")
+
+        with bs.Row(padding=(12, 8), gap=10, horizontal="stretch", vertical_items="center"):
+            search = bs.TextField(placeholder="Search icons", grow=True)
+            search.insert_addon("label", "before", icon="search")
+            bs.Label(textsignal=count, font="caption", accent="muted")
+
+        bs.Divider()
+
+        gallery = bs.Gallery(
+            data_source=source,
+            image_field="icon",
+            caption_field="name",
+            columns="auto",
+            tile_size=(72, 40),
+            fit="none",            # show the 32px glyph at native size — crisp, no upscale
+            gap=6,
+            selection_mode="single",
+            grow=True,
+            horizontal="stretch",
+        )
+
+        bs.Divider()
+
+        with bs.Row(padding=(12, 4), horizontal="stretch", surface="chrome"):
+            bs.Label(textsignal=status, font="caption", accent="muted")
+
+        def on_search(event) -> None:
+            query = event.text.strip().lower()
+            source.where(col("name").contains(query) if query else None)
+            gallery.reload()
+            update_count()
+
+        # Live, as-you-type filtering — debounced so a fast typist isn't reloaded
+        # on every keystroke.
+        search.on_input().debounce(120).listen(on_search)
+
+        def on_pick(record: dict) -> None:
+            name = record["name"]
+            set_clipboard(name)
+            status.set(f'Copied  "{name}"  —  ready to paste as  icon="{name}"')
+
+        gallery.on_item_click(on_pick)
+
+        update_count()
+
+    app.run()
+
+if __name__ == '__main__':
+    run_icons()

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")