bootstack 0.1.0a1__py3-none-any.whl

bootstack/cli/__init__.py

@@ -0,0 +1,124 @@
+"""CLI entry point for bootstack.
+
+The bootstack CLI provides commands for:
+- Creating new projects (start)
+- Running applications (run)
+- Building for distribution (build)
+- Adding components (add)
+- Listing resources (list)
+
+Usage:
+    bootstack start <appname>        Create a new project
+    bootstack run [path]             Run the application
+    bootstack promote --pyinstaller  Enable PyInstaller support
+    bootstack build                  Build for distribution
+    bootstack add page <ClassName>   Add a new page (AppShell)
+    bootstack add view <ClassName>   Add a new view
+    bootstack add dialog <ClassName> Add a new dialog
+    bootstack add theme <name>       Add a custom theme
+    bootstack add i18n               Add i18n support
+    bootstack list themes            List available themes
+    bootstack doctor                 Diagnose project and environment health
+    bootstack demo                   Launch the widget demo
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from typing import Sequence
+
+from bootstack.cli import add, build, doctor, list_cmd, promote, run, start
+from bootstack.cli.demo import run_demo
+
+
+def main(argv: Sequence[str] | None = None) -> None:
+    """Dispatch CLI commands registered in bootstack."""
+    parser = argparse.ArgumentParser(
+        prog="bootstack",
+        description="bootstack command line interface",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog="""\
+Examples:
+  bootstack start MyApp              Create a new project
+  bootstack start MyApp --template appshell  Create an AppShell project
+  bootstack start MyApp --theme superhero    Use a specific theme
+  bootstack run                      Run the application
+  bootstack promote --pyinstaller    Enable PyInstaller support
+  bootstack build                    Build for distribution
+  bootstack add view SettingsView    Add a new view
+  bootstack list themes              List available themes
+  bootstack doctor                   Diagnose project and environment health
+  bootstack demo                     Launch the widget demo
+
+For more information on a command:
+  bootstack <command> --help
+""",
+    )
+
+    parser.add_argument(
+        "--version",
+        action="version",
+        version=_get_version(),
+    )
+    parser.add_argument(
+        "-v",
+        "--verbose",
+        action="store_true",
+        help="Print full tracebacks on error",
+    )
+
+    subparsers = parser.add_subparsers(
+        dest="command",
+        title="commands",
+        metavar="<command>",
+    )
+
+    # Register commands
+    start.add_parser(subparsers)
+    run.add_parser(subparsers)
+    promote.add_parser(subparsers)
+    build.add_parser(subparsers)
+    add.add_parser(subparsers)
+    list_cmd.add_parser(subparsers)
+    doctor.add_parser(subparsers)
+
+    # Demo command (kept for backwards compatibility)
+    demo_parser = subparsers.add_parser(
+        "demo",
+        help="Launch the widget demo",
+    )
+    demo_parser.set_defaults(func=lambda args: run_demo())
+
+    # Parse arguments
+    args = parser.parse_args(argv)
+    func = getattr(args, "func", None)
+
+    if func is None:
+        parser.print_help()
+        sys.exit(0)
+
+    # Execute command
+    try:
+        func(args)
+    except KeyboardInterrupt:
+        print("\nInterrupted.")
+        sys.exit(1)
+    except Exception as e:
+        if getattr(args, "verbose", False):
+            import traceback
+            traceback.print_exc()
+        else:
+            print(f"Error: {e}")
+            print("(Run with --verbose for the full traceback.)")
+        sys.exit(1)
+
+
+def _get_version() -> str:
+    """Get the bootstack version string."""
+    try:
+        import bootstack
+
+        return f"bootstack {bootstack.__version__}"
+    except Exception:
+        return "bootstack (unknown version)"

bootstack/cli/__main__.py

@@ -0,0 +1,6 @@
+"""Allow running bootstack CLI as python -m bootstack.cli."""
+
+from bootstack.cli import main
+
+if __name__ == "__main__":
+    main()

bootstack/cli/add.py

@@ -0,0 +1,439 @@
+"""bootstack add command - Add views, dialogs, themes, and i18n to a project."""
+
+from __future__ import annotations
+
+import argparse
+from pathlib import Path
+
+from bootstack.cli.config import TtkbConfig, find_config
+from bootstack.cli.templates import create_dialog, create_page, create_view
+
+
+def add_parser(subparsers: argparse._SubParsersAction) -> None:
+    """Add the 'add' subcommand parser."""
+    parser = subparsers.add_parser(
+        "add",
+        help="Add components to the project",
+        description="Add views, pages, dialogs, themes, or i18n support to the project.",
+    )
+    add_subparsers = parser.add_subparsers(dest="component")
+
+    # bootstack add page <ClassName>
+    page_parser = add_subparsers.add_parser(
+        "page",
+        help="Add a new page (for AppShell projects)",
+    )
+    page_parser.add_argument(
+        "class_name",
+        help="Page class name (CamelCase, e.g., 'DashboardPage')",
+    )
+    page_parser.add_argument(
+        "--dir",
+        type=Path,
+        default=None,
+        help="Target directory (default: src/<app>/pages/)",
+    )
+    page_parser.add_argument(
+        "--scrollable",
+        action="store_true",
+        help="Make the page scrollable (wraps content in a ScrollView)",
+    )
+    page_parser.set_defaults(func=run_add_page)
+
+    # bootstack add view <ClassName>
+    view_parser = add_subparsers.add_parser(
+        "view",
+        help="Add a new view",
+    )
+    view_parser.add_argument(
+        "class_name",
+        help="View class name (CamelCase, e.g., 'SettingsView')",
+    )
+    view_parser.add_argument(
+        "--container",
+        choices=["grid", "pack"],
+        default=None,
+        help="Container type (default: from bootstack.toml or 'grid')",
+    )
+    view_parser.add_argument(
+        "--dir",
+        type=Path,
+        default=None,
+        help="Target directory (default: src/<app>/views/)",
+    )
+    view_parser.set_defaults(func=run_add_view)
+
+    # bootstack add dialog <ClassName>
+    dialog_parser = add_subparsers.add_parser(
+        "dialog",
+        help="Add a new dialog",
+    )
+    dialog_parser.add_argument(
+        "class_name",
+        help="Dialog class name (CamelCase, e.g., 'ConfirmDialog')",
+    )
+    dialog_parser.add_argument(
+        "--dir",
+        type=Path,
+        default=None,
+        help="Target directory (default: src/<app>/dialogs/)",
+    )
+    dialog_parser.set_defaults(func=run_add_dialog)
+
+    # bootstack add theme <name>
+    theme_parser = add_subparsers.add_parser(
+        "theme",
+        help="Add a custom theme",
+    )
+    theme_parser.add_argument(
+        "name",
+        help="Theme name (e.g., 'mytheme')",
+    )
+    theme_parser.add_argument(
+        "--mode",
+        choices=["light", "dark"],
+        default="light",
+        help="Theme mode (default: light)",
+    )
+    theme_parser.set_defaults(func=run_add_theme)
+
+    # bootstack add i18n
+    i18n_parser = add_subparsers.add_parser(
+        "i18n",
+        help="Add internationalization support",
+    )
+    i18n_parser.add_argument(
+        "--languages",
+        nargs="+",
+        default=["en"],
+        help="Languages to support (default: en)",
+    )
+    i18n_parser.set_defaults(func=run_add_i18n)
+
+    parser.set_defaults(func=lambda args: parser.print_help())
+
+
+def run_add_view(args: argparse.Namespace) -> None:
+    """Add a new view to the project."""
+    class_name = args.class_name
+
+    # Validate class name
+    if not class_name[0].isupper():
+        print("Error: Class name should be CamelCase (e.g., 'SettingsView')")
+        return
+
+    # Find project configuration
+    config_path = find_config()
+    if config_path is None:
+        print("Error: No bootstack.toml found. Are you in a bootstack project?")
+        return
+
+    project_root = config_path.parent
+    config = TtkbConfig.load(config_path)
+
+    # Reject in AppShell projects — views belong to the basic template
+    if config.app.template == "appshell":
+        print("Error: 'bootstack add view' is for basic-template projects.")
+        print("This project uses the 'appshell' template. Use 'bootstack add page' instead.")
+        return
+
+    # Determine container type
+    container = args.container
+    if container is None:
+        container = config.layout.default_container
+
+    # Determine target directory
+    if args.dir:
+        target_dir = args.dir
+    else:
+        # Parse entry point to find source directory
+        entry_path = Path(config.app.entry)
+        if entry_path.parts[0] == "src" and len(entry_path.parts) >= 2:
+            module_name = entry_path.parts[1]
+            target_dir = project_root / "src" / module_name / "views"
+        else:
+            target_dir = project_root / "views"
+
+    target_dir.mkdir(parents=True, exist_ok=True)
+
+    # Ensure __init__.py exists
+    init_file = target_dir / "__init__.py"
+    if not init_file.exists():
+        init_file.write_text('"""Views package."""\n', encoding="utf-8")
+
+    # Create view
+    file_path = create_view(class_name, target_dir, container)
+
+    print(f"Created view: {file_path.relative_to(project_root)}")
+
+
+def run_add_page(args: argparse.Namespace) -> None:
+    """Add a new page to an AppShell project."""
+    class_name = args.class_name
+
+    # Validate class name
+    if not class_name[0].isupper():
+        print("Error: Class name should be CamelCase (e.g., 'DashboardPage')")
+        return
+
+    # Find project configuration
+    config_path = find_config()
+    if config_path is None:
+        print("Error: No bootstack.toml found. Are you in a bootstack project?")
+        return
+
+    project_root = config_path.parent
+    config = TtkbConfig.load(config_path)
+
+    # Check that this is an AppShell project
+    if config.app.template != "appshell":
+        print("Error: 'bootstack add page' is for AppShell projects.")
+        print("This project uses the 'basic' template. Use 'bootstack add view' instead.")
+        return
+
+    # Determine target directory and module name for the import hint
+    entry_path = Path(config.app.entry)
+    if entry_path.parts[0] == "src" and len(entry_path.parts) >= 2:
+        module_name = entry_path.parts[1]
+        default_target = project_root / "src" / module_name / "pages"
+    else:
+        module_name = None
+        default_target = project_root / "pages"
+
+    target_dir = args.dir if args.dir else default_target
+
+    target_dir.mkdir(parents=True, exist_ok=True)
+
+    # Ensure __init__.py exists
+    init_file = target_dir / "__init__.py"
+    if not init_file.exists():
+        init_file.write_text('"""Pages package."""\n', encoding="utf-8")
+
+    # Create page
+    scrollable = args.scrollable
+    file_path = create_page(class_name, target_dir, scrollable=scrollable)
+
+    print(f"Created page: {file_path.relative_to(project_root)}")
+    print()
+    print("This created the file only — it is NOT yet shown in the sidebar.")
+    print("To register it with the AppShell, paste these lines into main.py:")
+    print()
+    import_module = f"{module_name}.pages" if module_name else "<module>.pages"
+    print(f"  from {import_module}.{file_path.stem} import {class_name}")
+    scrollable_arg = ", scrollable=True" if scrollable else ""
+    print(f'  page = shell.add_page("<id>", text="<Label>", icon="<icon>"{scrollable_arg})')
+    print(f"  {class_name}(page)")
+
+
+def run_add_dialog(args: argparse.Namespace) -> None:
+    """Add a new dialog to the project."""
+    class_name = args.class_name
+
+    # Validate class name
+    if not class_name[0].isupper():
+        print("Error: Class name should be CamelCase (e.g., 'ConfirmDialog')")
+        return
+
+    # Find project configuration
+    config_path = find_config()
+    if config_path is None:
+        print("Error: No bootstack.toml found. Are you in a bootstack project?")
+        return
+
+    project_root = config_path.parent
+    config = TtkbConfig.load(config_path)
+
+    # Determine target directory
+    if args.dir:
+        target_dir = args.dir
+    else:
+        # Parse entry point to find source directory
+        entry_path = Path(config.app.entry)
+        if entry_path.parts[0] == "src" and len(entry_path.parts) >= 2:
+            module_name = entry_path.parts[1]
+            target_dir = project_root / "src" / module_name / "dialogs"
+        else:
+            target_dir = project_root / "dialogs"
+
+    target_dir.mkdir(parents=True, exist_ok=True)
+
+    # Ensure __init__.py exists
+    init_file = target_dir / "__init__.py"
+    if not init_file.exists():
+        init_file.write_text('"""Dialogs package."""\n', encoding="utf-8")
+
+    # Create dialog
+    file_path = create_dialog(class_name, target_dir)
+
+    print(f"Created dialog: {file_path.relative_to(project_root)}")
+
+
+def run_add_theme(args: argparse.Namespace) -> None:
+    """Add a custom theme to the project."""
+    theme_name = args.name.lower()
+    mode = args.mode
+
+    # Find project configuration
+    config_path = find_config()
+    if config_path is None:
+        print("Error: No bootstack.toml found. Are you in a bootstack project?")
+        return
+
+    project_root = config_path.parent
+
+    # Create themes directory
+    themes_dir = project_root / "themes"
+    themes_dir.mkdir(exist_ok=True)
+
+    # Create theme file
+    theme_file = themes_dir / f"{theme_name}.json"
+    if theme_file.exists():
+        print(f"Error: Theme '{theme_name}' already exists.")
+        return
+
+    # Theme template based on mode
+    if mode == "light":
+        theme_content = _get_light_theme_template(theme_name)
+    else:
+        theme_content = _get_dark_theme_template(theme_name)
+
+    theme_file.write_text(theme_content, encoding="utf-8")
+
+    print(f"Created theme: {theme_file.relative_to(project_root)}")
+    print()
+    print("To use this theme, register the JSON file before creating your App:")
+    print()
+    print("  from bootstack.style.theme_provider import register_user_theme")
+    print(f'  register_user_theme("{theme_name}", "themes/{theme_name}.json")')
+    print(f'  app = ttk.App(theme="{theme_name}")')
+
+
+def run_add_i18n(args: argparse.Namespace) -> None:
+    """Add internationalization support to the project."""
+    languages = args.languages
+
+    # Find project configuration
+    config_path = find_config()
+    if config_path is None:
+        print("Error: No bootstack.toml found. Are you in a bootstack project?")
+        return
+
+    project_root = config_path.parent
+
+    # Create locales directory structure
+    locales_dir = project_root / "locales"
+
+    for lang in languages:
+        lang_dir = locales_dir / lang / "LC_MESSAGES"
+        lang_dir.mkdir(parents=True, exist_ok=True)
+
+        # Create .po file template
+        po_file = lang_dir / "messages.po"
+        if not po_file.exists():
+            po_content = _get_po_template(lang)
+            po_file.write_text(po_content, encoding="utf-8")
+            print(f"Created: {po_file.relative_to(project_root)}")
+
+    print()
+    print("Internationalization support added!")
+    print()
+    print("Next steps:")
+    print("  1. Add translatable strings to your .po files")
+    print("  2. Compile with: msgfmt locales/<lang>/LC_MESSAGES/messages.po -o locales/<lang>/LC_MESSAGES/messages.mo")
+    print("  3. Use translations in code: ttk.mc('Hello')")
+
+
+_BASE_SHADES = {
+    "blue": "#0d6efd",
+    "indigo": "#6610f2",
+    "purple": "#6f42c1",
+    "red": "#dc3545",
+    "orange": "#fd7e14",
+    "yellow": "#ffc107",
+    "green": "#198754",
+    "teal": "#20c997",
+    "cyan": "#0dcaf0",
+    "gray": "#adb5bd",
+    "pink": "#d63384",
+}
+
+
+def _theme_display_name(name: str) -> str:
+    return " ".join(part.capitalize() for part in name.replace("_", "-").split("-") if part)
+
+
+def _render_theme(name: str, mode: str) -> str:
+    """Render a v2 theme JSON template.
+
+    Light themes use the [600] step for semantic accents (so text on white
+    has good contrast); dark themes use [400] (lighter accents on a dark
+    background). Both schemas match the format consumed by
+    `bootstack.style.theme_provider`.
+    """
+    if mode == "light":
+        foreground, background, step = "#212529", "#ffffff", "600"
+    else:
+        foreground, background, step = "#f8f9fa", "#212529", "400"
+
+    payload = {
+        "name": name,
+        "display_name": _theme_display_name(name),
+        "mode": mode,
+        "foreground": foreground,
+        "background": background,
+        "white": "#ffffff",
+        "black": "#000000",
+        "shades": _BASE_SHADES,
+        "semantic": {
+            "primary": f"blue[{step}]",
+            "secondary": f"gray[{step}]",
+            "success": f"green[{step}]",
+            "info": f"cyan[{step}]",
+            "warning": f"yellow[{step}]",
+            "danger": f"red[{step}]",
+            "light": "gray[100]",
+            "dark": "gray[900]",
+        },
+    }
+    import json as _json
+    return _json.dumps(payload, indent=2) + "\n"
+
+
+def _get_light_theme_template(name: str) -> str:
+    """Get a v2 light-mode theme template."""
+    return _render_theme(name, "light")
+
+
+def _get_dark_theme_template(name: str) -> str:
+    """Get a v2 dark-mode theme template."""
+    return _render_theme(name, "dark")
+
+
+def _get_po_template(lang: str) -> str:
+    """Get a .po file template."""
+    from datetime import datetime, timezone
+
+    now = datetime.now(timezone.utc).strftime("%Y-%m-%d %H:%M%z")
+
+    return f'''\
+# {lang.upper()} translations for the application.
+# Copyright (C) YEAR THE PACKAGE'S COPYRIGHT HOLDER
+# This file is distributed under the same license as the PACKAGE package.
+#
+msgid ""
+msgstr ""
+"Project-Id-Version: 1.0\\n"
+"Report-Msgid-Bugs-To: \\n"
+"POT-Creation-Date: {now}\\n"
+"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\\n"
+"Last-Translator: FULL NAME <EMAIL@ADDRESS>\\n"
+"Language-Team: {lang.upper()} <LL@li.org>\\n"
+"Language: {lang}\\n"
+"MIME-Version: 1.0\\n"
+"Content-Type: text/plain; charset=UTF-8\\n"
+"Content-Transfer-Encoding: 8bit\\n"
+
+# Example translation
+# msgid "Hello"
+# msgstr "Hello"
+'''

bootstack/cli/build.py

@@ -0,0 +1,115 @@
+"""bootstack build command - Build the application for distribution."""
+
+from __future__ import annotations
+
+import argparse
+import shutil
+import subprocess
+import sys
+from pathlib import Path
+
+from bootstack.cli.config import TtkbConfig, find_config
+
+
+def add_parser(subparsers: argparse._SubParsersAction) -> None:
+    """Add the 'build' subcommand parser."""
+    parser = subparsers.add_parser(
+        "build",
+        help="Build the application for distribution",
+        description="Build the application using the configured build backend.",
+    )
+    parser.add_argument(
+        "--clean",
+        action="store_true",
+        help="Clean build artifacts before building",
+    )
+    parser.set_defaults(func=run_build)
+
+
+def run_build(args: argparse.Namespace) -> None:
+    """Execute the build command."""
+    # 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 project has been promoted
+    if config.build is None:
+        print("Error: Project has not been promoted for building.")
+        print("Run 'bootstack promote --pyinstaller' first.")
+        return
+
+    backend = config.build.backend
+
+    if backend == "pyinstaller":
+        _build_pyinstaller(config, project_root, clean=args.clean)
+    else:
+        print(f"Error: Unknown build backend '{backend}'")
+        return
+
+
+def _build_pyinstaller(
+    config: TtkbConfig,
+    project_root: Path,
+    clean: bool = False,
+) -> None:
+    """Build using PyInstaller."""
+    # Check if PyInstaller is installed
+    try:
+        import PyInstaller  # noqa: F401
+    except ImportError:
+        print("Error: PyInstaller is not installed.")
+        print("Install it with: pip install pyinstaller")
+        return
+
+    spec_path = project_root / "build" / "pyinstaller" / "app.spec"
+    if not spec_path.exists():
+        print("Error: PyInstaller spec file not found.")
+        print("Run 'bootstack promote --pyinstaller' to generate it.")
+        return
+
+    # Clean if requested
+    if clean:
+        print("Cleaning build artifacts...")
+        dist_dir = project_root / "dist"
+        build_dir = project_root / "build" / "pyinstaller" / "build"
+        if dist_dir.exists():
+            shutil.rmtree(dist_dir)
+        if build_dir.exists():
+            shutil.rmtree(build_dir)
+
+    print(f"Building '{config.app.name}' with PyInstaller...")
+    print()
+
+    # Run PyInstaller
+    cmd = [
+        sys.executable,
+        "-m",
+        "PyInstaller",
+        str(spec_path),
+        "--distpath",
+        str(project_root / "dist"),
+        "--workpath",
+        str(project_root / "build" / "pyinstaller" / "build"),
+        "--noconfirm",
+    ]
+
+    try:
+        result = subprocess.run(cmd, cwd=str(project_root))
+        if result.returncode == 0:
+            print()
+            print("Build completed successfully!")
+            print()
+            print(f"Output: {project_root / 'dist' / config.app.name}")
+        else:
+            print()
+            print("Build failed.")
+            sys.exit(result.returncode)
+    except KeyboardInterrupt:
+        print("\nBuild interrupted.")
+        sys.exit(1)