mlx-stack 0.3.6__tar.gz → 0.3.7__tar.gz

mlx_stack-0.3.7/.release-please-manifest.json

@@ -0,0 +1,3 @@
+{
+  ".": "0.3.7"
+}

{mlx_stack-0.3.6 → mlx_stack-0.3.7}/CHANGELOG.md

@@ -4,12 +4,29 @@ All notable changes to this project will be documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.3.7](https://github.com/weklund/mlx-stack/compare/v0.3.6...v0.3.7) (2026-04-04)
+
+
+### Features
+
+* branded welcome screen for bare CLI invocation ([#37](https://github.com/weklund/mlx-stack/issues/37)) ([b4becc9](https://github.com/weklund/mlx-stack/commit/b4becc9a2a4407eb98708c9116b5193286bb23f0))
+
+
+### Security
+
+* bump pygments from 2.19.2 to 2.20.0 — fixes catastrophic backtracking in archetype, devicetree, and Lua lexers ([#36](https://github.com/weklund/mlx-stack/issues/36)) ([15859f1](https://github.com/weklund/mlx-stack/commit/15859f1))
+
 ## [0.3.6](https://github.com/weklund/mlx-stack/compare/v0.3.5...v0.3.6) (2026-04-04)
 
 
+### Security
+
+* add explicit `permissions: contents: read` to CI, nightly, and pre-release workflows to enforce least-privilege on GITHUB_TOKEN ([#34](https://github.com/weklund/mlx-stack/issues/34)) ([0f8bfb0](https://github.com/weklund/mlx-stack/commit/0f8bfb0a17df82142261284f8d6405918ae6b759))
+
+
 ### Bug Fixes
 
-* add explicit permissions to CI and integration workflows ([#34](https://github.com/weklund/mlx-stack/issues/34)) ([0f8bfb0](https://github.com/weklund/mlx-stack/commit/0f8bfb0a17df82142261284f8d6405918ae6b759))
+* replace sleep-based sync with polling in flaky follow test ([#34](https://github.com/weklund/mlx-stack/issues/34))
 
 ## [0.3.5](https://github.com/weklund/mlx-stack/compare/v0.3.4...v0.3.5) (2026-04-04)
 

{mlx_stack-0.3.6 → mlx_stack-0.3.7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mlx-stack
-Version: 0.3.6
+Version: 0.3.7
 Summary: CLI control plane for local LLM infrastructure on Apple Silicon
 Project-URL: Homepage, https://github.com/weklund/mlx-stack
 Project-URL: Repository, https://github.com/weklund/mlx-stack

{mlx_stack-0.3.6 → mlx_stack-0.3.7}/src/mlx_stack/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '0.3.6'
-__version_tuple__ = version_tuple = (0, 3, 6)
+__version__ = version = '0.3.7'
+__version_tuple__ = version_tuple = (0, 3, 7)
 
 __commit_id__ = commit_id = None

mlx_stack-0.3.7/src/mlx_stack/cli/main.py

@@ -0,0 +1,300 @@
+"""Main CLI entry point for mlx-stack.
+
+Provides the top-level Click command group with --help, --version,
+Rich-formatted output, and typo suggestions for unknown subcommands.
+"""
+
+from __future__ import annotations
+
+import difflib
+
+import click
+from rich.console import Console
+from rich.table import Table
+from rich.text import Text
+
+from mlx_stack import __version__
+from mlx_stack.cli.bench import bench as bench_command
+from mlx_stack.cli.config import config as config_group
+from mlx_stack.cli.down import down as down_command
+from mlx_stack.cli.init import init as init_command
+from mlx_stack.cli.install import install as install_command
+from mlx_stack.cli.install import uninstall as uninstall_command
+from mlx_stack.cli.logs import logs as logs_command
+from mlx_stack.cli.models import models as models_command
+from mlx_stack.cli.profile import profile as profile_command
+from mlx_stack.cli.pull import pull as pull_command
+from mlx_stack.cli.recommend import recommend as recommend_command
+from mlx_stack.cli.setup import setup as setup_command
+from mlx_stack.cli.status import status as status_command
+from mlx_stack.cli.up import up as up_command
+from mlx_stack.cli.watch import watch as watch_command
+
+console = Console(stderr=True)
+
+# ASCII banner — block-character logo, each row is (color, text) pairs
+# Visual width: ~78 columns, fits 80-col terminals
+_BANNER_LINES = [
+    ("cyan", "  ███╗   ███╗ ██╗     ██╗  ██╗"),
+    ("white", "  ███████╗████████╗ █████╗  ██████╗██╗  ██╗"),
+    ("cyan", "  ████╗ ████║ ██║     ╚██╗██╔╝"),
+    ("white", "  ██╔════╝╚══██╔══╝██╔══██╗██╔════╝██║ ██╔╝"),
+    ("cyan", "  ██╔████╔██║ ██║      ╚███╔╝ "),
+    ("white", "  ███████╗   ██║   ███████║██║     █████╔╝ "),
+    ("cyan", "  ██║╚██╔╝██║ ██║      ██╔██╗ "),
+    ("white", "  ╚════██║   ██║   ██╔══██║██║     ██╔═██╗ "),
+    ("cyan", "  ██║ ╚═╝ ██║ ███████╗██╔╝ ██╗"),
+    ("white", " ███████║   ██║   ██║  ██║╚██████╗██║  ██╗"),
+    ("cyan", "  ╚═╝     ╚═╝ ╚══════╝╚═╝  ╚═╝"),
+    ("white", " ╚══════╝   ╚═╝   ╚═╝  ╚═╝ ╚═════╝╚═╝  ╚═╝"),
+]
+
+# Command categories and their members
+_COMMAND_CATEGORIES: dict[str, list[str]] = {
+    "Setup & Configuration": ["setup", "profile", "config", "init"],
+    "Model Management": ["recommend", "models", "pull"],
+    "Stack Lifecycle": ["up", "down", "status", "watch", "install", "uninstall"],
+    "Diagnostics": ["bench", "logs"],
+}
+
+
+def _get_quick_status() -> list[tuple[str, str]]:
+    """Gather lightweight, read-only status info.
+
+    Only reads files that already exist — never creates directories.
+    Returns a list of (label, value) pairs for display.
+    """
+    items: list[tuple[str, str]] = []
+
+    # Chip — read profile.json if it exists
+    try:
+        from mlx_stack.core.paths import get_profile_path
+
+        profile_path = get_profile_path()
+        if profile_path.exists():
+            from mlx_stack.core.hardware import load_profile
+
+            profile = load_profile()
+            if profile:
+                mem = f"{profile.memory_gb}GB"
+                items.append(("Chip", f"{profile.chip}  {mem} unified"))
+    except Exception:
+        pass
+
+    # Stack — check if a stack definition exists
+    try:
+        from mlx_stack.core.paths import get_stacks_dir
+
+        stack_dir = get_stacks_dir()
+        if stack_dir.exists() and (stack_dir / "default.yaml").exists():
+            items.append(("Stack", "configured"))
+        else:
+            items.append(("Stack", "not configured"))
+    except Exception:
+        pass
+
+    return items
+
+
+def _render_welcome(ctx: click.Context, group: RichGroup) -> None:
+    """Render the branded welcome screen for bare `mlx-stack` invocation."""
+    out = Console()
+
+    # Banner
+    out.print()
+    for i in range(0, len(_BANNER_LINES), 2):
+        left_color, left_text = _BANNER_LINES[i]
+        right_color, right_text = _BANNER_LINES[i + 1]
+        line = Text(left_text, style=f"bold {left_color}")
+        line.append(right_text, style=f"bold {right_color}")
+        out.print(line, highlight=False)
+    out.print()
+
+    # Version line
+    ver_line = Text("  v" + __version__, style="dim")
+    ver_line.append("  ")
+    ver_line.append("Local LLM infrastructure on Apple Silicon", style="italic")
+    out.print(ver_line)
+    out.print()
+
+    # Quick status (read-only, best-effort)
+    status_items = _get_quick_status()
+    if status_items:
+        for label, value in status_items:
+            line = Text(f"  {label}: ", style="bold")
+            style = "green" if value != "not configured" else "yellow"
+            line.append(value, style=style)
+            out.print(line)
+        out.print()
+
+    # Grouped commands
+    commands = group.list_commands(ctx)
+    if commands:
+        for category_name, cmd_names in _COMMAND_CATEGORIES.items():
+            cmds_in_cat = []
+            for cmd_name in cmd_names:
+                if cmd_name in commands:
+                    cmd = group.get_command(ctx, cmd_name)
+                    if cmd:
+                        cmds_in_cat.append(
+                            (cmd_name, cmd.get_short_help_str(limit=60))
+                        )
+            if not cmds_in_cat:
+                continue
+
+            out.print(Text(f"  {category_name}", style="bold yellow"))
+            cmd_table = Table(
+                show_header=False,
+                box=None,
+                padding=(0, 2),
+                pad_edge=False,
+            )
+            cmd_table.add_column(style="green", min_width=14)
+            cmd_table.add_column(style="dim")
+            for name, help_text in cmds_in_cat:
+                cmd_table.add_row(f"    {name}", help_text)
+            out.print(cmd_table)
+            out.print()
+
+    # Get started nudge
+    if not status_items or all(v == "not configured" for _, v in status_items):
+        out.print(
+            Text("  Get started: ", style="bold")
+            + Text("mlx-stack setup", style="bold cyan")
+        )
+    else:
+        out.print(
+            Text("  Run ", style="dim")
+            + Text("mlx-stack <command> --help", style="dim bold")
+            + Text(" for details on any command.", style="dim")
+        )
+    out.print()
+
+
+class RichGroup(click.Group):
+    """Custom Click Group with Rich-formatted help and typo suggestions."""
+
+    def format_help(self, ctx: click.Context, formatter: click.HelpFormatter) -> None:
+        """Format help text using Rich tables."""
+        console_out = Console()
+
+        # Title
+        console_out.print()
+        title = Text("mlx-stack", style="bold cyan")
+        title.append(" — CLI control plane for local LLM infrastructure on Apple Silicon")
+        console_out.print(title)
+        console_out.print()
+
+        # Usage
+        usage = Text("Usage: ", style="bold") + Text("mlx-stack [OPTIONS] COMMAND [ARGS]...")
+        console_out.print(usage)
+        console_out.print()
+
+        # Options
+        console_out.print(Text("Options:", style="bold yellow"))
+        options_table = Table(show_header=False, box=None, padding=(0, 2))
+        options_table.add_column(style="green", min_width=20)
+        options_table.add_column()
+        options_table.add_row("--version", "Show version and exit.")
+        options_table.add_row("--help", "Show this message and exit.")
+        console_out.print(options_table)
+        console_out.print()
+
+        # Commands grouped by category
+        commands = self.list_commands(ctx)
+        if commands:
+            for category_name, cmd_names in _COMMAND_CATEGORIES.items():
+                cmds_in_cat = []
+                for cmd_name in cmd_names:
+                    if cmd_name in commands:
+                        cmd = self.get_command(ctx, cmd_name)
+                        if cmd:
+                            cmds_in_cat.append(
+                                (cmd_name, cmd.get_short_help_str(limit=80))
+                            )
+                if not cmds_in_cat:
+                    continue
+
+                console_out.print(Text(f"{category_name}:", style="bold yellow"))
+                cmd_table = Table(show_header=False, box=None, padding=(0, 2))
+                cmd_table.add_column(style="green", min_width=20)
+                cmd_table.add_column()
+                for name, help_text in cmds_in_cat:
+                    cmd_table.add_row(name, help_text)
+                console_out.print(cmd_table)
+                console_out.print()
+
+    def resolve_command(
+        self, ctx: click.Context, args: list[str]
+    ) -> tuple[str | None, click.Command | None, list[str]]:
+        """Override resolve_command to provide typo suggestions."""
+        try:
+            return super().resolve_command(ctx, args)
+        except click.UsageError:
+            # Get the attempted command name
+            if args:
+                cmd_name = args[0]
+                available = self.list_commands(ctx)
+                matches = difflib.get_close_matches(cmd_name, available, n=3, cutoff=0.5)
+
+                error_msg = f"Error: No such command '{cmd_name}'."
+                if matches:
+                    suggestions = ", ".join(f"'{m}'" for m in matches)
+                    error_msg += f"\n\nDid you mean one of these?\n    {suggestions}"
+                error_msg += "\n\nRun 'mlx-stack --help' for a list of available commands."
+
+                console.print(f"[red]{error_msg}[/red]")
+                ctx.exit(2)
+                raise SystemExit(2)  # noqa: B904 — we want to exit, not chain
+            raise
+
+
+def version_callback(ctx: click.Context, _param: click.Parameter, value: bool) -> None:
+    """Print version and exit."""
+    if not value or ctx.resilient_parsing:
+        return
+    click.echo(f"mlx-stack, version {__version__}")
+    ctx.exit(0)
+
+
+@click.group(cls=RichGroup, invoke_without_command=True)
+@click.option(
+    "--version",
+    is_flag=True,
+    callback=version_callback,
+    expose_value=False,
+    is_eager=True,
+    help="Show version and exit.",
+)
+@click.pass_context
+def cli(ctx: click.Context) -> None:
+    """CLI control plane for local LLM infrastructure on Apple Silicon."""
+    if ctx.invoked_subcommand is None:
+        _render_welcome(ctx, ctx.command)  # type: ignore[arg-type]
+
+
+# --- Placeholder commands for planned features ---
+# These will be replaced by real implementations in subsequent features.
+
+
+cli.add_command(setup_command, "setup")
+cli.add_command(profile_command, "profile")
+cli.add_command(recommend_command, "recommend")
+cli.add_command(init_command, "init")
+
+
+cli.add_command(pull_command, "pull")
+cli.add_command(models_command, "models")
+cli.add_command(up_command, "up")
+cli.add_command(down_command, "down")
+cli.add_command(status_command, "status")
+
+
+cli.add_command(watch_command, "watch")
+cli.add_command(install_command, "install")
+cli.add_command(uninstall_command, "uninstall")
+
+cli.add_command(bench_command, "bench")
+cli.add_command(logs_command, "logs")
+
+cli.add_command(config_group, "config")

{mlx_stack-0.3.6 → mlx_stack-0.3.7}/tests/unit/test_cli.py

@@ -50,6 +50,35 @@ class TestCLIHelp:
         assert result.exit_code == 0
         assert "mlx-stack" in result.output
 
+    def test_bare_command_shows_banner(self) -> None:
+        runner = CliRunner()
+        result = runner.invoke(cli, [])
+        assert result.exit_code == 0
+        # Banner contains box-drawing characters from the ASCII art
+        assert "███" in result.output
+
+    def test_bare_command_shows_version(self) -> None:
+        runner = CliRunner()
+        result = runner.invoke(cli, [])
+        assert __version__ in result.output
+
+    def test_bare_command_shows_command_categories(self) -> None:
+        runner = CliRunner()
+        result = runner.invoke(cli, [])
+        assert "Setup & Configuration" in result.output
+        assert "Model Management" in result.output
+        assert "Stack Lifecycle" in result.output
+        assert "Diagnostics" in result.output
+
+    def test_bare_command_shows_get_started(
+        self, clean_mlx_stack_home: Path,
+    ) -> None:
+        """When no profile/stack exists, shows 'Get started' nudge."""
+        runner = CliRunner()
+        result = runner.invoke(cli, [])
+        assert result.exit_code == 0
+        assert "mlx-stack setup" in result.output
+
 
 class TestCLIVersion:
     """Tests for --version output."""

{mlx_stack-0.3.6 → mlx_stack-0.3.7}/uv.lock

@@ -363,11 +363,11 @@ wheels = [
 
 [[package]]
 name = "pygments"
-version = "2.19.2"
+version = "2.20.0"
 source = { registry = "https://pypi.org/simple" }
-sdist = { url = "https://files.pythonhosted.org/packages/b0/77/a5b8c569bf593b0140bde72ea885a803b82086995367bf2037de0159d924/pygments-2.19.2.tar.gz", hash = "sha256:636cb2477cec7f8952536970bc533bc43743542f70392ae026374600add5b887", size = 4968631, upload-time = "2025-06-21T13:39:12.283Z" }
+sdist = { url = "https://files.pythonhosted.org/packages/c3/b2/bc9c9196916376152d655522fdcebac55e66de6603a76a02bca1b6414f6c/pygments-2.20.0.tar.gz", hash = "sha256:6757cd03768053ff99f3039c1a36d6c0aa0b263438fcab17520b30a303a82b5f", size = 4955991, upload-time = "2026-03-29T13:29:33.898Z" }
 wheels = [
-    { url = "https://files.pythonhosted.org/packages/c7/21/705964c7812476f378728bdf590ca4b771ec72385c533964653c68e86bdc/pygments-2.19.2-py3-none-any.whl", hash = "sha256:86540386c03d588bb81d44bc3928634ff26449851e99741617ecb9037ee5ec0b", size = 1225217, upload-time = "2025-06-21T13:39:07.939Z" },
+    { url = "https://files.pythonhosted.org/packages/f4/7e/a72dd26f3b0f4f2bf1dd8923c85f7ceb43172af56d63c7383eb62b332364/pygments-2.20.0-py3-none-any.whl", hash = "sha256:81a9e26dd42fd28a23a2d169d86d7ac03b46e2f8b59ed4698fb4785f946d0176", size = 1231151, upload-time = "2026-03-29T13:29:30.038Z" },
 ]
 
 [[package]]

mlx_stack-0.3.6/.release-please-manifest.json

@@ -1,3 +0,0 @@
-{
-  ".": "0.3.6"
-}

mlx_stack-0.3.6/src/mlx_stack/cli/main.py

@@ -1,190 +0,0 @@
-"""Main CLI entry point for mlx-stack.
-
-Provides the top-level Click command group with --help, --version,
-Rich-formatted output, and typo suggestions for unknown subcommands.
-"""
-
-from __future__ import annotations
-
-import difflib
-
-import click
-from rich.console import Console
-from rich.table import Table
-from rich.text import Text
-
-from mlx_stack import __version__
-from mlx_stack.cli.bench import bench as bench_command
-from mlx_stack.cli.config import config as config_group
-from mlx_stack.cli.down import down as down_command
-from mlx_stack.cli.init import init as init_command
-from mlx_stack.cli.install import install as install_command
-from mlx_stack.cli.install import uninstall as uninstall_command
-from mlx_stack.cli.logs import logs as logs_command
-from mlx_stack.cli.models import models as models_command
-from mlx_stack.cli.profile import profile as profile_command
-from mlx_stack.cli.pull import pull as pull_command
-from mlx_stack.cli.recommend import recommend as recommend_command
-from mlx_stack.cli.setup import setup as setup_command
-from mlx_stack.cli.status import status as status_command
-from mlx_stack.cli.up import up as up_command
-from mlx_stack.cli.watch import watch as watch_command
-
-console = Console(stderr=True)
-
-
-class RichGroup(click.Group):
-    """Custom Click Group with Rich-formatted help and typo suggestions."""
-
-    def format_help(self, ctx: click.Context, formatter: click.HelpFormatter) -> None:
-        """Format help text using Rich tables."""
-        console_out = Console()
-
-        # Title
-        console_out.print()
-        title = Text("mlx-stack", style="bold cyan")
-        title.append(" — CLI control plane for local LLM infrastructure on Apple Silicon")
-        console_out.print(title)
-        console_out.print()
-
-        # Usage
-        usage = Text("Usage: ", style="bold") + Text("mlx-stack [OPTIONS] COMMAND [ARGS]...")
-        console_out.print(usage)
-        console_out.print()
-
-        # Options
-        console_out.print(Text("Options:", style="bold yellow"))
-        options_table = Table(show_header=False, box=None, padding=(0, 2))
-        options_table.add_column(style="green", min_width=20)
-        options_table.add_column()
-        options_table.add_row("--version", "Show version and exit.")
-        options_table.add_row("--help", "Show this message and exit.")
-        console_out.print(options_table)
-        console_out.print()
-
-        # Commands grouped by category
-        commands = self.list_commands(ctx)
-        if commands:
-            # Group commands by category
-            categories: dict[str, list[tuple[str, str]]] = {
-                "Setup & Configuration": [],
-                "Model Management": [],
-                "Stack Lifecycle": [],
-                "Diagnostics": [],
-            }
-
-            command_categories = {
-                "setup": "Setup & Configuration",
-                "profile": "Setup & Configuration",
-                "config": "Setup & Configuration",
-                "init": "Setup & Configuration",
-                "recommend": "Model Management",
-                "models": "Model Management",
-                "pull": "Model Management",
-                "up": "Stack Lifecycle",
-                "down": "Stack Lifecycle",
-                "status": "Stack Lifecycle",
-                "watch": "Stack Lifecycle",
-                "install": "Stack Lifecycle",
-                "uninstall": "Stack Lifecycle",
-                "bench": "Diagnostics",
-                "logs": "Diagnostics",
-            }
-
-            for cmd_name in commands:
-                cmd = self.get_command(ctx, cmd_name)
-                if cmd is None:
-                    continue
-                help_text = cmd.get_short_help_str(limit=80)
-                category = command_categories.get(cmd_name, "Other")
-                if category in categories:
-                    categories[category].append((cmd_name, help_text))
-                else:
-                    categories.setdefault("Other", []).append((cmd_name, help_text))
-
-            for category_name, cmds in categories.items():
-                if not cmds:
-                    continue
-                console_out.print(Text(f"{category_name}:", style="bold yellow"))
-                cmd_table = Table(show_header=False, box=None, padding=(0, 2))
-                cmd_table.add_column(style="green", min_width=20)
-                cmd_table.add_column()
-                for cmd_name, help_text in cmds:
-                    cmd_table.add_row(cmd_name, help_text)
-                console_out.print(cmd_table)
-                console_out.print()
-
-    def resolve_command(
-        self, ctx: click.Context, args: list[str]
-    ) -> tuple[str | None, click.Command | None, list[str]]:
-        """Override resolve_command to provide typo suggestions."""
-        try:
-            return super().resolve_command(ctx, args)
-        except click.UsageError:
-            # Get the attempted command name
-            if args:
-                cmd_name = args[0]
-                available = self.list_commands(ctx)
-                matches = difflib.get_close_matches(cmd_name, available, n=3, cutoff=0.5)
-
-                error_msg = f"Error: No such command '{cmd_name}'."
-                if matches:
-                    suggestions = ", ".join(f"'{m}'" for m in matches)
-                    error_msg += f"\n\nDid you mean one of these?\n    {suggestions}"
-                error_msg += "\n\nRun 'mlx-stack --help' for a list of available commands."
-
-                console.print(f"[red]{error_msg}[/red]")
-                ctx.exit(2)
-                raise SystemExit(2)  # noqa: B904 — we want to exit, not chain
-            raise
-
-
-def version_callback(ctx: click.Context, _param: click.Parameter, value: bool) -> None:
-    """Print version and exit."""
-    if not value or ctx.resilient_parsing:
-        return
-    click.echo(f"mlx-stack, version {__version__}")
-    ctx.exit(0)
-
-
-@click.group(cls=RichGroup, invoke_without_command=True)
-@click.option(
-    "--version",
-    is_flag=True,
-    callback=version_callback,
-    expose_value=False,
-    is_eager=True,
-    help="Show version and exit.",
-)
-@click.pass_context
-def cli(ctx: click.Context) -> None:
-    """CLI control plane for local LLM infrastructure on Apple Silicon."""
-    if ctx.invoked_subcommand is None:
-        click.echo(ctx.get_help())
-
-
-# --- Placeholder commands for planned features ---
-# These will be replaced by real implementations in subsequent features.
-
-
-cli.add_command(setup_command, "setup")
-cli.add_command(profile_command, "profile")
-cli.add_command(recommend_command, "recommend")
-cli.add_command(init_command, "init")
-
-
-cli.add_command(pull_command, "pull")
-cli.add_command(models_command, "models")
-cli.add_command(up_command, "up")
-cli.add_command(down_command, "down")
-cli.add_command(status_command, "status")
-
-
-cli.add_command(watch_command, "watch")
-cli.add_command(install_command, "install")
-cli.add_command(uninstall_command, "uninstall")
-
-cli.add_command(bench_command, "bench")
-cli.add_command(logs_command, "logs")
-
-cli.add_command(config_group, "config")