krita-cli 1.0.0__py3-none-any.whl

krita_cli/__init__.py

@@ -0,0 +1,5 @@
+"""Krita CLI — Typer-based command-line interface."""
+
+from krita_cli.app import app
+
+__all__ = ["app"]

krita_cli/_shared.py

@@ -0,0 +1,94 @@
+"""Shared CLI utilities used by app.py and command modules."""
+
+from __future__ import annotations
+
+from contextlib import contextmanager
+from typing import Any
+
+import typer
+from rich.console import Console
+from typer import Context
+
+from krita_cli.config_cmd import load_config
+from krita_client import (
+    ClientConfig,
+    ErrorCode,
+    KritaClient,
+    KritaError,
+)
+
+console = Console()
+
+
+class CLIState:
+    """Shared state passed through Typer context."""
+
+    def __init__(self) -> None:
+        self.url: str | None = None
+
+
+def _handle_error(exc: KritaError) -> None:
+    """Display a Krita client error and exit."""
+    console.print(f"[red]Error:[/red] {exc.message}")
+    if exc.code:
+        console.print(f"[dim]Code: {exc.code}[/dim]")
+
+    if exc.recoverable:
+        if exc.code == ErrorCode.NO_ACTIVE_DOCUMENT:
+            console.print("[green]Hint: Open a document or create a new canvas first.[/green]")
+        elif exc.code == ErrorCode.INVALID_PARAMETERS:
+            console.print("[green]Hint: Check your input values are within allowed ranges.[/green]")
+        elif exc.code == ErrorCode.LAYER_NOT_FOUND:
+            console.print("[green]Hint: Ensure there is an active paint layer in your document.[/green]")
+        elif exc.code == ErrorCode.PLUGIN_UNREACHABLE:
+            console.print("[green]Hint: Make sure Krita is running with the MCP plugin enabled.[/green]")
+        elif exc.code == ErrorCode.COMMAND_TIMEOUT:
+            console.print("[green]Hint: The operation took too long. Try again or check Krita status.[/green]")
+        elif exc.code == ErrorCode.BRUSH_NOT_FOUND:
+            console.print("[green]Hint: Check the brush preset name or list available brushes first.[/green]")
+        elif exc.code == ErrorCode.FILE_NOT_FOUND:
+            console.print("[green]Hint: Verify the file path exists and is accessible.[/green]")
+        else:
+            console.print(
+                "[green]Hint: This error appears to be recoverable. Adjust your request and try again.[/green]"
+            )
+
+    raise typer.Exit(code=1)
+
+
+@contextmanager
+def _handle_errors() -> Any:
+    """Context manager to handle Krita errors gracefully."""
+    try:
+        yield
+    except KritaError as exc:
+        _handle_error(exc)
+
+
+def _get_client(ctx: Context) -> KritaClient:
+    """Create a Krita client from the Typer context."""
+    state: CLIState = ctx.obj or CLIState()
+    if state.url is not None:
+        config = ClientConfig(url=state.url)
+    else:
+        plugin_config = load_config()
+        port = plugin_config.get("port", 5678)
+        config = ClientConfig(url=f"http://localhost:{port}")
+    return KritaClient(config)
+
+
+def _format_result(result: dict[str, object]) -> None:
+    """Display a command result in a readable format."""
+    if "error" in result:
+        console.print(f"[red]Error:[/red] {result['error']}")
+        raise typer.Exit(code=1)
+    for key, value in result.items():  # pragma: no cover - display-only
+        if key == "status":
+            continue
+        console.print(f"[dim]{key}:[/dim] {value}")
+
+
+def _print_result(result: dict[str, object], message: str) -> None:
+    """Display a command result with a custom message."""
+    console.print(f"[green]{message}[/green]")
+    _format_result(result)

krita_cli/app.py

@@ -0,0 +1,149 @@
+"""Krita CLI — Main application composition."""
+
+from __future__ import annotations
+
+import sys
+from typing import Annotated
+
+import typer
+from typer import Context
+
+from krita_cli import _shared
+from krita_cli.commands import config as _config
+from krita_client import (
+    KritaCommandError,
+    KritaConnectionError,
+    KritaValidationError,
+)
+
+app = typer.Typer(
+    name="krita",
+    help="CLI for programmatic painting in Krita via the MCP plugin.",
+    no_args_is_help=True,
+    add_completion=False,
+)
+app.add_typer(_config.app, name="config")
+console = _shared.console
+
+# Re-export shared utilities for backward compatibility
+CLIState = _shared.CLIState
+_handle_error = _shared._handle_error
+_get_client = _shared._get_client
+_format_result = _shared._format_result
+
+
+# -- Global options -----------------------------------------------------------
+
+
+@app.callback()
+def callback(
+    ctx: Context,
+    url: Annotated[
+        str | None,
+        typer.Option("--url", "-u", help="Krita plugin URL (overrides KRITA_URL env var)"),
+    ] = None,
+) -> None:
+    """Krita CLI — programmatic painting in Krita."""
+    ctx.obj = CLIState()
+    ctx.obj.url = url
+
+
+# -- Register sub-apps --------------------------------------------------------
+# Lazy imports to avoid circular dependency between app.py and command modules.
+from krita_cli.commands import (
+    batch as _batch,
+)
+from krita_cli.commands import (
+    brush as _brush,
+)
+from krita_cli.commands import (
+    call as _call,
+)
+from krita_cli.commands import (
+    canvas as _canvas,
+)
+from krita_cli.commands import (
+    color as _color,
+)
+from krita_cli.commands import (
+    file_ops as _file_ops,
+)
+from krita_cli.commands import (
+    health as _health,
+)
+from krita_cli.commands import (
+    history_cmd as _history_cmd,
+)
+from krita_cli.commands import (
+    introspect as _introspect,
+)
+from krita_cli.commands import (
+    layers as _layers,
+)
+from krita_cli.commands import (
+    navigation as _navigation,
+)
+from krita_cli.commands import (
+    replay as _replay,
+)
+from krita_cli.commands import (
+    rollback as _rollback,
+)
+from krita_cli.commands import (
+    selection as _selection,
+)
+from krita_cli.commands import (
+    stroke as _stroke,
+)
+
+app.add_typer(_canvas.app, name="canvas")
+app.add_typer(_color.app, name="color")
+app.add_typer(_brush.app, name="brush")
+app.add_typer(_stroke.app, name="stroke")
+app.add_typer(_navigation.app, name="navigation")
+app.add_typer(_file_ops.app, name="file")
+app.add_typer(_health.app)
+app.add_typer(_call.app)
+app.add_typer(_history_cmd.app)
+app.add_typer(_batch.app)
+app.add_typer(_rollback.app)
+app.add_typer(_introspect.app, name="introspect")
+app.add_typer(_layers.app, name="layers")
+app.add_typer(_replay.app)
+app.add_typer(_selection.app, name="selection")
+
+# Re-export command functions for backward compatibility (cli.py shim)
+new_canvas = _canvas.new_canvas
+get_canvas = _canvas.get_canvas
+save = _canvas.save
+clear = _canvas.clear
+set_color = _color.set_color
+get_color_at = _color.get_color_at
+set_brush = _brush.set_brush
+list_brushes = _brush.list_brushes
+stroke = _stroke.stroke
+fill = _stroke.fill
+draw_shape = _stroke.draw_shape
+undo = _navigation.undo
+redo = _navigation.redo
+open_file = _file_ops.open_file
+health = _health.health
+call = _call.call
+
+
+# -- Entry point --------------------------------------------------------------
+
+
+def main() -> None:  # pragma: no cover
+    """Main entry point for the CLI."""
+    try:
+        app()
+    except (KritaConnectionError, KritaCommandError, KritaValidationError) as exc:
+        _handle_error(exc)
+    except KeyboardInterrupt:
+        console.print("\n[dim]Interrupted.[/dim]")
+        sys.exit(130)
+
+
+if __name__ == "__main__":  # pragma: no cover
+    main()

krita_cli/cli.py

@@ -0,0 +1,59 @@
+"""Krita CLI — Compatibility shim.
+
+All functionality has moved to krita_cli.app.
+This module re-exports everything for backward compatibility.
+"""
+
+from krita_cli.app import (
+    CLIState,
+    _format_result,
+    _get_client,
+    _handle_error,
+    app,
+    call,
+    callback,
+    clear,
+    console,
+    draw_shape,
+    fill,
+    get_canvas,
+    get_color_at,
+    health,
+    list_brushes,
+    main,
+    new_canvas,
+    open_file,
+    redo,
+    save,
+    set_brush,
+    set_color,
+    stroke,
+    undo,
+)
+
+__all__ = [
+    "CLIState",
+    "_format_result",
+    "_get_client",
+    "_handle_error",
+    "app",
+    "call",
+    "callback",
+    "clear",
+    "console",
+    "draw_shape",
+    "fill",
+    "get_canvas",
+    "get_color_at",
+    "health",
+    "list_brushes",
+    "main",
+    "new_canvas",
+    "open_file",
+    "redo",
+    "save",
+    "set_brush",
+    "set_color",
+    "stroke",
+    "undo",
+]

krita_cli/commands/__init__.py

@@ -0,0 +1 @@
+"""CLI command sub-applications."""

krita_cli/commands/batch.py

@@ -0,0 +1,86 @@
+"""Batch command CLI command."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Annotated, Any, cast
+
+import typer
+from rich.console import Console
+from typer import Context
+
+from krita_cli import _shared
+from krita_client import KritaError
+
+console = Console()
+
+app = typer.Typer()
+
+
+@app.command()
+def batch(
+    ctx: Context,
+    file: Annotated[Path, typer.Argument(help="JSON file with batch commands")],
+    stop_on_error: Annotated[bool, typer.Option("--stop-on-error", help="Stop on first error")] = False,
+) -> None:
+    """Execute multiple commands from a JSON file.
+
+    The JSON file should contain an array of command objects, each with
+    an "action" and optional "params" key.
+
+    Example JSON file:
+    [
+        {"action": "set_color", "params": {"color": "#ff0000"}},
+        {"action": "stroke", "params": {"points": [[0, 0], [100, 100]]}},
+        {"action": "fill", "params": {"x": 200, "y": 200, "radius": 30}}
+    ]
+    """
+    try:
+        commands = json.loads(file.read_text())
+    except json.JSONDecodeError as exc:
+        console.print(f"[red]Error:[/red] Invalid JSON in {file}: {exc}")
+        raise typer.Exit(code=1) from exc
+    except OSError as exc:
+        console.print(f"[red]Error:[/red] Cannot read {file}: {exc}")
+        raise typer.Exit(code=1) from exc
+
+    if not isinstance(commands, list):
+        console.print("[red]Error:[/red] JSON file must contain an array of commands.")
+        raise typer.Exit(code=1)
+
+    try:
+        client = _shared._get_client(ctx)
+        result = client.batch_execute(commands, stop_on_error=stop_on_error)
+        status = result.get("status", "unknown")
+        results_raw = result.get("results", [])
+        if not isinstance(results_raw, list):
+            results_raw = []
+        results = cast("list[dict[str, Any]]", results_raw)
+
+        ok = sum(1 for r in results if isinstance(r, dict) and r.get("status") == "ok")
+        errs = sum(1 for r in results if isinstance(r, dict) and r.get("status") == "error")
+        count = result.get("count", 0)
+        color = "green" if status == "ok" else "red" if status == "error" else "yellow"
+        console.print(f"[{color}]Batch: {status}[/{color}]")
+        console.print(f"  {ok} succeeded, {errs} failed out of {count}")
+        batch_id = result.get("batch_id")
+        if batch_id:
+            console.print(f"  Batch ID: [dim]{batch_id}[/dim]")
+        if errs > 0:
+            console.print("[red]Errors:[/red]")
+            for r in results:
+                if isinstance(r, dict) and r.get("status") == "error":
+                    err_msg = r.get("error")
+                    if not err_msg:
+                        result_data = r.get("result", {})
+                        if isinstance(result_data, dict) and "error" in result_data:
+                            err_info = result_data["error"]
+                            err_msg = (
+                                err_info.get("message", str(err_info)) if isinstance(err_info, dict) else str(err_info)
+                            )
+                    if not err_msg:
+                        err_msg = "unknown"
+                    console.print(f"  [red]✗ {r.get('action', 'unknown')}: {err_msg}[/red]")
+    except KritaError as exc:
+        _shared._handle_error(exc)

krita_cli/commands/brush.py

@@ -0,0 +1,58 @@
+"""Brush-related CLI commands: set-brush, list-brushes."""
+
+from __future__ import annotations
+
+from typing import Annotated
+
+import typer
+from rich.console import Console
+from rich.table import Table
+from typer import Context
+
+from krita_cli import _shared
+from krita_client import KritaError
+
+console = Console()
+
+app = typer.Typer()
+
+
+@app.command("set-brush")
+def set_brush(
+    ctx: Context,
+    preset: Annotated[str | None, typer.Option("--preset", "-p", help="Brush preset name")] = None,
+    size: Annotated[int | None, typer.Option("--size", "-s", help="Brush size in pixels")] = None,
+    opacity: Annotated[float | None, typer.Option("--opacity", "-o", help="Brush opacity (0.0-1.0)")] = None,
+) -> None:
+    """Set brush preset and properties."""
+    try:
+        client = _shared._get_client(ctx)
+        result = client.set_brush(preset=preset, size=size, opacity=opacity)
+        _shared._format_result(result)
+    except KritaError as exc:
+        _shared._handle_error(exc)
+
+
+@app.command("list-brushes")
+def list_brushes(
+    ctx: Context,
+    filter: Annotated[str, typer.Option("--filter", "-f", help="Filter by name")] = "",  # noqa: A002
+    limit: Annotated[int, typer.Option("--limit", "-l", help="Maximum number to return")] = 20,
+) -> None:
+    """List available brush presets."""
+    try:
+        client = _shared._get_client(ctx)
+        result = client.list_brushes(filter=filter, limit=limit)
+        brushes_raw = result.get("brushes", [])
+        brushes = list(brushes_raw) if isinstance(brushes_raw, list) else []
+        if not brushes:
+            console.print("No brushes found matching filter.")
+            return
+        table = Table(title=f"Available Brushes ({len(brushes)})")
+        table.add_column("#", style="dim")
+        table.add_column("Name")
+        for i, name in enumerate(brushes, 1):
+            table.add_row(str(i), name)
+        console.print(table)
+    except KritaError as exc:
+        _shared._handle_error(exc)

krita_cli/commands/call.py

@@ -0,0 +1,49 @@
+"""Raw command mode CLI command: call."""
+
+from __future__ import annotations
+
+import json
+from typing import Annotated
+
+import typer
+from rich.console import Console
+from typer import Context
+
+from krita_cli import _shared
+from krita_client import KritaError
+
+console = Console()
+
+app = typer.Typer()
+
+
+@app.command()
+def call(
+    ctx: Context,
+    action: Annotated[str, typer.Argument(help="Command action name")],
+    params_json: Annotated[str | None, typer.Argument(help="JSON params string")] = None,
+) -> None:
+    """Send a raw command to the Krita plugin.
+
+    Useful for commands not yet exposed as subcommands, or for scripting.
+
+    \b
+    Examples:
+        krita call new_canvas '{"width": 1920, "height": 1080}'
+        krita call set_color '{"color": "#ff0000"}'
+        krita call stroke '{"points": [[0,0],[100,100]]}'
+    """
+    params: dict[str, object] = {}
+    if params_json:
+        try:
+            params = json.loads(params_json)
+        except json.JSONDecodeError as exc:
+            console.print(f"[red]Error:[/red] Invalid JSON: {exc}")
+            raise typer.Exit(code=1) from exc
+
+    try:
+        client = _shared._get_client(ctx)
+        result = client.send_command(action, params)
+        console.print(json.dumps(result, indent=2, default=str))
+    except KritaError as exc:
+        _shared._handle_error(exc)

krita_cli/commands/canvas.py

@@ -0,0 +1,77 @@
+"""Canvas-related CLI commands: new-canvas, get-canvas, save, clear."""
+
+from __future__ import annotations
+
+from typing import Annotated
+
+import typer
+from rich.console import Console
+from typer import Context
+
+from krita_cli import _shared
+from krita_client import KritaError
+
+console = Console()
+
+app = typer.Typer()
+
+
+@app.command("new-canvas")
+def new_canvas(
+    ctx: Context,
+    width: Annotated[int, typer.Option("--width", "-W", help="Canvas width in pixels")] = 800,
+    height: Annotated[int, typer.Option("--height", "-H", help="Canvas height in pixels")] = 600,
+    name: Annotated[str, typer.Option("--name", "-n", help="Document name")] = "New Canvas",
+    background: Annotated[str, typer.Option("--background", "-b", help="Background color (hex)")] = "#1a1a2e",
+) -> None:
+    """Create a new canvas in Krita."""
+    try:
+        client = _shared._get_client(ctx)
+        result = client.new_canvas(width=width, height=height, name=name, background=background)
+        _shared._format_result(result)
+    except KritaError as exc:
+        _shared._handle_error(exc)
+
+
+@app.command("get-canvas")
+def get_canvas(
+    ctx: Context,
+    filename: Annotated[str, typer.Option("--filename", "-f", help="Output filename")] = "canvas.png",
+) -> None:
+    """Export the current canvas to a PNG file."""
+    console.print("[dim]Exporting canvas (this may take a while for large canvases)...[/dim]")
+    try:
+        client = _shared._get_client(ctx)
+        result = client.get_canvas(filename=filename)
+        _shared._format_result(result)
+    except KritaError as exc:
+        _shared._handle_error(exc)
+
+
+@app.command()
+def save(
+    ctx: Context,
+    path: Annotated[str, typer.Argument(help="Full file path to save to")],
+) -> None:
+    """Save the current canvas to a specific file path."""
+    console.print("[dim]Saving canvas (this may take a while for large canvases)...[/dim]")
+    try:
+        client = _shared._get_client(ctx)
+        result = client.save(path=path)
+        _shared._format_result(result)
+    except KritaError as exc:
+        _shared._handle_error(exc)
+
+
+@app.command()
+def clear(
+    ctx: Context,
+    color: Annotated[str, typer.Option("--color", "-c", help="Color to fill with")] = "#1a1a2e",
+) -> None:
+    """Clear the canvas to a solid color."""
+    try:
+        client = _shared._get_client(ctx)
+        result = client.clear(color=color)
+        _shared._format_result(result)
+    except KritaError as exc:
+        _shared._handle_error(exc)

krita_cli/commands/color.py

@@ -0,0 +1,42 @@
+"""Color-related CLI commands: set-color, get-color-at."""
+
+from __future__ import annotations
+
+from typing import Annotated
+
+import typer
+from typer import Context
+
+from krita_cli import _shared
+from krita_client import KritaError
+
+app = typer.Typer()
+
+
+@app.command("set-color")
+def set_color(
+    ctx: Context,
+    color: Annotated[str, typer.Argument(help="Hex color code (e.g., #ff6b6b)")],
+) -> None:
+    """Set the foreground paint color."""
+    try:
+        client = _shared._get_client(ctx)
+        result = client.set_color(color=color)
+        _shared._format_result(result)
+    except KritaError as exc:
+        _shared._handle_error(exc)
+
+
+@app.command("get-color-at")
+def get_color_at(
+    ctx: Context,
+    x: Annotated[int, typer.Argument(help="X coordinate")],
+    y: Annotated[int, typer.Argument(help="Y coordinate")],
+) -> None:
+    """Sample the color at a specific pixel (eyedropper)."""
+    try:
+        client = _shared._get_client(ctx)
+        result = client.get_color_at(x=x, y=y)
+        _shared._format_result(result)
+    except KritaError as exc:
+        _shared._handle_error(exc)

krita_cli/commands/config.py

@@ -0,0 +1,48 @@
+"""CLI commands for plugin configuration: show, set, reset."""
+
+from __future__ import annotations
+
+from typing import Annotated
+
+import typer
+from rich.console import Console
+from rich.table import Table
+
+from krita_cli import config_cmd
+
+app = typer.Typer(name="config", help="Plugin configuration commands.")
+console = Console()
+
+
+@app.command("show")
+def config_show() -> None:
+    """Show current plugin configuration."""
+    config = config_cmd.load_config()
+    table = Table(title=f"Plugin Config ({config_cmd.CONFIG_FILE})")
+    table.add_column("Key", style="cyan")
+    table.add_column("Value", style="green")
+    for key, value in config.items():
+        table.add_row(str(key), str(value))
+    console.print(table)
+
+
+@app.command("set")
+def config_set(
+    key: Annotated[str, typer.Argument(help="Configuration key")],
+    value: Annotated[str, typer.Argument(help="Configuration value")],
+) -> None:
+    """Set a plugin configuration value."""
+    try:
+        config_cmd.set_key(key, value)
+    except ValueError as exc:
+        console.print(f"[red]Error:[/red] {exc}")
+        raise typer.Exit(1) from exc
+    console.print(f"[green]Set {key} = {value}[/green]")
+    console.print("[dim]Restart Krita for changes to take effect.[/dim]")
+
+
+@app.command("reset")
+def config_reset() -> None:
+    """Reset plugin configuration to defaults."""
+    config_cmd.reset_config()
+    console.print("[green]Configuration reset to defaults.[/green]")