clutterxp 1.1.0__py3-none-any.whl

clutterxp/cli/cmd_service.py

@@ -0,0 +1,130 @@
+"""Command handlers for `clutterxp service` subcommands."""
+
+from __future__ import annotations
+
+import sys
+from typing import TYPE_CHECKING, Annotated, Any
+
+import typer
+
+from clutterxp.cli.errors import handle_errors
+from clutterxp.cli.render import get_console, print_json
+
+if TYPE_CHECKING:
+    from clutterxp.cli.app import GlobalOptions
+
+service_app = typer.Typer(
+    help="Manage systemd user service for clutterxp watch",
+    no_args_is_help=True,
+)
+
+
+def _get_installer() -> Any:
+    """Import and return the service_install module, or exit with a helpful message."""
+    import importlib
+
+    try:
+        return importlib.import_module("clutterxp.service_install")
+    except (ImportError, ModuleNotFoundError):
+        sys.stderr.write(
+            "Service management is not available in this installation "
+            "(clutterxp.service_install module not found).\n"
+        )
+        raise typer.Exit(code=1) from None
+
+
+@service_app.command("install")
+def service_install_command(ctx: typer.Context) -> None:
+    """Install and enable systemd user unit for clutterxp watch."""
+    from clutterxp.cli.app import get_globals
+
+    opts: GlobalOptions = get_globals(ctx)
+    with handle_errors(json_mode=opts.json_mode, command_name="service_install"):
+        installer = _get_installer()
+        res = installer.install()
+        if opts.json_mode:
+            print_json(
+                {
+                    "schema_version": 1,
+                    "command": "service_install",
+                    "status": "installed",
+                    "detail": str(res),
+                }
+            )
+        else:
+            get_console(no_color=opts.no_color).print("Service installed and enabled.")
+
+
+@service_app.command("uninstall")
+def service_uninstall_command(ctx: typer.Context) -> None:
+    """Disable and remove systemd user unit for clutterxp watch."""
+    from clutterxp.cli.app import get_globals
+
+    opts: GlobalOptions = get_globals(ctx)
+    with handle_errors(json_mode=opts.json_mode, command_name="service_uninstall"):
+        installer = _get_installer()
+        res = installer.uninstall()
+        if opts.json_mode:
+            print_json(
+                {
+                    "schema_version": 1,
+                    "command": "service_uninstall",
+                    "status": "uninstalled",
+                    "detail": str(res),
+                }
+            )
+        else:
+            get_console(no_color=opts.no_color).print("Service uninstalled.")
+
+
+@service_app.command("status")
+def service_status_command(ctx: typer.Context) -> None:
+    """Check status of systemd user service."""
+    from clutterxp.cli.app import get_globals
+
+    opts: GlobalOptions = get_globals(ctx)
+    with handle_errors(json_mode=opts.json_mode, command_name="service_status"):
+        installer = _get_installer()
+        st = installer.status()
+        if opts.json_mode:
+            print_json(
+                {
+                    "schema_version": 1,
+                    "command": "service_status",
+                    "status": str(st),
+                }
+            )
+        else:
+            get_console(no_color=opts.no_color).print(f"Service status: {st}")
+
+
+@service_app.command("logs")
+def service_logs_command(
+    ctx: typer.Context,
+    lines: Annotated[
+        int,
+        typer.Option("--lines", "-n", help="Number of log lines to show"),
+    ] = 50,
+) -> None:
+    """View recent logs from the systemd user service."""
+    from clutterxp.cli.app import get_globals
+
+    opts: GlobalOptions = get_globals(ctx)
+    with handle_errors(json_mode=opts.json_mode, command_name="service_logs"):
+        installer = _get_installer()
+        log_content = installer.logs(lines=lines)
+        if opts.json_mode:
+            print_json(
+                {
+                    "schema_version": 1,
+                    "command": "service_logs",
+                    "lines": lines,
+                    "content": str(log_content),
+                }
+            )
+        else:
+            sys.stdout.write(str(log_content))
+            sys.stdout.flush()
+
+
+__all__ = ["service_app"]

clutterxp/cli/cmd_undo.py

@@ -0,0 +1,180 @@
+"""Command handler for `clutterxp undo`."""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+from typing import TYPE_CHECKING, Annotated
+
+import typer
+
+from clutterxp.cli.errors import handle_errors
+from clutterxp.cli.render import get_console, print_json, safe_str
+from clutterxp.models import OpStatus, SafetyRefusal
+
+if TYPE_CHECKING:
+    from clutterxp.cli.app import GlobalOptions
+
+
+def undo_command(
+    ctx: typer.Context,
+    op: Annotated[
+        int | None,
+        typer.Option("--op", help="Undo a single operation by ID"),
+    ] = None,
+    batch: Annotated[
+        int | None,
+        typer.Option("--batch", "-b", help="Undo all operations in a batch"),
+    ] = None,
+    file: Annotated[
+        Path | None,
+        typer.Option(
+            "--file",
+            help="Undo the last operation that moved this destination file",
+        ),
+    ] = None,
+    dry_run: Annotated[
+        bool,
+        typer.Option(
+            "-n",
+            "--dry-run",
+            help="Check undo preconditions without modifying files",
+        ),
+    ] = False,
+    yes: Annotated[
+        bool,
+        typer.Option(
+            "-y",
+            "--yes",
+            help="Skip confirmation prompt for undoing the last batch",
+        ),
+    ] = False,
+    on_conflict: Annotated[
+        str,
+        typer.Option(
+            "--on-conflict",
+            help="Origin collision behavior: skip | rename",
+        ),
+    ] = "skip",
+    allow_modified: Annotated[
+        bool,
+        typer.Option(
+            "--allow-modified",
+            help="Allow undo even if destination file size or mtime has changed",
+        ),
+    ] = False,
+) -> None:
+    """Safely undo previous file operations under journal-first protocol."""
+    from clutterxp.cli.app import build_organizer, get_globals
+
+    opts: GlobalOptions = get_globals(ctx)
+
+    if on_conflict not in ("skip", "rename"):
+        sys.stderr.write(
+            f"error: Invalid --on-conflict value '{on_conflict}'. Must be 'skip' or 'rename'.\n"
+        )
+        raise typer.Exit(code=2)
+
+    with handle_errors(json_mode=opts.json_mode, command_name="undo"):
+        organizer = build_organizer(opts.config)
+
+        # Default selector: last batch
+        target_batch = batch
+        if op is None and batch is None and file is None:
+            last_batch = organizer.history.last_batch_id()
+            if last_batch is None:
+                if opts.json_mode:
+                    print_json(
+                        {
+                            "schema_version": 1,
+                            "command": "undo",
+                            "dry_run": dry_run,
+                            "outcomes": [],
+                        }
+                    )
+                else:
+                    get_console(no_color=opts.no_color).print("No batches found to undo.")
+                return
+
+            ops = organizer.history.list_ops(batch_id=last_batch, status=OpStatus.DONE)
+            if not ops:
+                if opts.json_mode:
+                    print_json(
+                        {
+                            "schema_version": 1,
+                            "command": "undo",
+                            "dry_run": dry_run,
+                            "outcomes": [],
+                        }
+                    )
+                else:
+                    get_console(no_color=opts.no_color).print(
+                        f"Batch #{last_batch} has no completed operations to undo."
+                    )
+                return
+
+            if not yes and not dry_run and not opts.json_mode:
+                if not sys.stdin.isatty():
+                    raise SafetyRefusal(
+                        f"Refused: confirmation required to undo last batch #{last_batch} "
+                        f"({len(ops)} files) in non-interactive session. Pass --yes to confirm."
+                    )
+                confirmed = typer.confirm(
+                    f"Undo last batch #{last_batch}: {len(ops)} files?", default=True
+                )
+                if not confirmed:
+                    get_console(no_color=opts.no_color).print("Aborted.")
+                    raise typer.Exit(code=0)
+
+            target_batch = last_batch
+
+        outcomes = organizer.undo_service.undo(
+            op_id=op,
+            batch_id=target_batch,
+            file_path=file,
+            dry_run=dry_run,
+            on_conflict=on_conflict,
+            allow_modified=allow_modified,
+        )
+
+        success_count = sum(1 for o in outcomes if o.ok)
+        refused_count = len(outcomes) - success_count
+
+        if opts.json_mode:
+            outcomes_json = [
+                {
+                    "op_id": o.op_id,
+                    "ok": o.ok,
+                    "restored_to": safe_str(o.restored_to) if o.restored_to else None,
+                    "code": o.code.value,
+                    "message": o.message,
+                }
+                for o in outcomes
+            ]
+            print_json(
+                {
+                    "schema_version": 1,
+                    "command": "undo",
+                    "dry_run": dry_run,
+                    "outcomes": outcomes_json,
+                }
+            )
+        else:
+            console = get_console(no_color=opts.no_color)
+            prefix = r"\[dry-run] " if dry_run else ""
+            for o in outcomes:
+                if o.ok:
+                    target_str = safe_str(o.restored_to) if o.restored_to else ""
+                    console.print(f" {prefix}RESTORE  op #{o.op_id} -> {target_str}")
+                else:
+                    console.print(f" {prefix}REFUSE   op #{o.op_id} ({o.code.value}): {o.message}")
+
+            console.print(
+                f"\n{prefix}Summary: {success_count} restored, {refused_count} refused/failed"
+            )
+
+        if refused_count > 0:
+            raise typer.Exit(code=3)
+
+
+__all__ = ["undo_command"]

clutterxp/cli/cmd_watch.py

@@ -0,0 +1,147 @@
+"""Command handler for `clutterxp watch`."""
+
+from __future__ import annotations
+
+import signal
+from pathlib import Path
+from typing import TYPE_CHECKING, Annotated, Any
+
+import typer
+
+from clutterxp import paths
+from clutterxp.cli.errors import handle_errors
+from clutterxp.cli.render import get_console, print_json, render_plan, safe_str
+from clutterxp.models import PlanStatus
+from clutterxp.watch.service import WatchService
+
+if TYPE_CHECKING:
+    from clutterxp.cli.app import GlobalOptions
+
+
+def watch_command(
+    ctx: typer.Context,
+    paths_arg: Annotated[
+        list[Path] | None,
+        typer.Argument(
+            metavar="PATH",
+            help="Folders to watch (defaults to configured watch folders)",
+        ),
+    ] = None,
+    poll: Annotated[
+        bool,
+        typer.Option(
+            "--poll",
+            help="Use polling observer instead of inotify",
+        ),
+    ] = False,
+    dry_run: Annotated[
+        bool,
+        typer.Option(
+            "-n",
+            "--dry-run",
+            help="Run watch service in dry-run mode (log moves without moving)",
+        ),
+    ] = False,
+    once: Annotated[
+        bool,
+        typer.Option(
+            "--once",
+            help="Perform a single scan-and-organize pass and exit",
+        ),
+    ] = False,
+) -> None:
+    """Run the background directory watcher service."""
+    from clutterxp.cli.app import build_organizer, get_globals
+
+    opts: GlobalOptions = get_globals(ctx)
+    target_config = opts.config if opts.config is not None else paths.config_path()
+
+    with handle_errors(json_mode=opts.json_mode, command_name="watch"):
+        organizer = build_organizer(target_config)
+
+        if once:
+            # Single scan pass
+            plan = organizer.plan(paths=paths_arg if paths_arg else None)
+            if dry_run:
+                if opts.json_mode:
+                    print_json(
+                        {
+                            "schema_version": 1,
+                            "command": "watch",
+                            "mode": "once",
+                            "dry_run": True,
+                            "summary": {
+                                "will_move": plan.count(PlanStatus.WILL_MOVE)
+                                + plan.count(PlanStatus.WILL_MOVE_RENAMED),
+                                "unmatched": plan.count(PlanStatus.NO_MATCH)
+                                + plan.count(PlanStatus.IGNORED),
+                                "ambiguous": plan.count(PlanStatus.AMBIGUOUS),
+                                "blocked": plan.count(PlanStatus.BLOCKED),
+                            },
+                        }
+                    )
+                else:
+                    render_plan(plan, dry_run=True, no_color=opts.no_color)
+            else:
+                batch_res = organizer.apply(plan, command="watch")
+                if opts.json_mode:
+                    print_json(
+                        {
+                            "schema_version": 1,
+                            "command": "watch",
+                            "mode": "once",
+                            "dry_run": False,
+                            "batch_id": batch_res.batch_id,
+                            "summary": {
+                                "moved": batch_res.moved,
+                                "skipped": batch_res.skipped,
+                                "blocked": batch_res.blocked,
+                                "failed": batch_res.failed,
+                            },
+                        }
+                    )
+                else:
+                    console = get_console(no_color=opts.no_color)
+                    console.print(
+                        f"Watch pass complete: {batch_res.moved} moved, "
+                        f"{batch_res.skipped} skipped, {batch_res.blocked} blocked, "
+                        f"{batch_res.failed} failed"
+                    )
+            return
+
+        # Continuous watch mode
+        def on_event_cb(event_data: dict[str, Any]) -> None:
+            if opts.json_mode:
+                print_json(event_data)
+            elif not opts.quiet:
+                kind = event_data.get("kind", "")
+                p = event_data.get("path", "")
+                status = event_data.get("status", "")
+                console = get_console(no_color=opts.no_color)
+                console.print(f"[{kind}] {safe_str(p)}: {status}")
+
+        service = WatchService(
+            config_path=target_config,
+            organizer=organizer,
+            poll=poll,
+            dry_run=dry_run,
+            on_event=on_event_cb,
+        )
+
+        def sig_handler(signum: int, frame: Any) -> None:
+            service.stop()
+
+        signal.signal(signal.SIGINT, sig_handler)
+        signal.signal(signal.SIGTERM, sig_handler)
+
+        if not opts.quiet and not opts.json_mode:
+            console = get_console(no_color=opts.no_color)
+            console.print("Watching folders... Press Ctrl+C to stop.")
+
+        try:
+            service.run()
+        except KeyboardInterrupt:
+            service.stop()
+
+
+__all__ = ["watch_command"]

clutterxp/cli/errors.py

@@ -0,0 +1,166 @@
+"""Error handling and exit code mapping for ClutterXP CLI.
+
+Exit codes per docs/08_CLI.md:
+  0: success (including nothing to do)
+  1: unexpected error (traceback written to log, short message to stderr)
+  2: usage or configuration error
+  3: partial failure (some files failed/blocked/refused) or --strict with ambiguity
+  4: refused by safety rule (root, denylist, confirmation required in non-interactive session)
+  5: lock held by another instance
+"""
+
+from __future__ import annotations
+
+import functools
+import logging
+import sys
+from collections.abc import Callable, Generator
+from contextlib import contextmanager
+from typing import Any, ParamSpec, TypeVar
+
+import typer
+
+from clutterxp.models import ClutterError, ConfigError, ErrorCode, SafetyRefusal
+
+logger = logging.getLogger("clutterxp.cli")
+
+P = ParamSpec("P")
+R = TypeVar("R")
+
+
+def exit_with_code(code: int) -> None:
+    """Exit cleanly with the given exit code using typer.Exit."""
+    raise typer.Exit(code=code)
+
+
+@contextmanager
+def handle_errors(
+    *,
+    json_mode: bool = False,
+    command_name: str | None = None,
+) -> Generator[None, None, None]:
+    """Context manager to trap exceptions and map them to appropriate CLI exit codes.
+
+    Can also be used directly inside commands or as a decorator.
+    """
+    try:
+        yield
+    except typer.Exit:
+        # Pass through deliberate typer exit codes
+        raise
+    except typer.Abort:
+        # Typer user cancel (Ctrl-C or abort)
+        raise typer.Exit(code=1) from None
+    except SafetyRefusal as e:
+        is_lock = e.code == ErrorCode.LOCK_TIMEOUT or "lock" in str(e).lower()
+        exit_code = 5 if is_lock else 4
+        msg = f"error: {e.message or str(e)}"
+        if json_mode:
+            import json
+
+            sys.stdout.write(
+                json.dumps(
+                    {
+                        "schema_version": 1,
+                        "command": command_name or "unknown",
+                        "error": str(e),
+                        "code": exit_code,
+                    }
+                )
+                + "\n"
+            )
+        else:
+            sys.stderr.write(f"{msg}\n")
+        raise typer.Exit(code=exit_code) from None
+    except ConfigError as e:
+        if json_mode:
+            import json
+
+            payload: dict[str, Any] = {
+                "schema_version": 1,
+                "command": command_name or "unknown",
+                "error": str(e),
+                "code": 2,
+            }
+            if e.problems:
+                payload["problems"] = list(e.problems)
+            sys.stdout.write(json.dumps(payload) + "\n")
+        else:
+            if e.problems:
+                for p in e.problems:
+                    sys.stderr.write(f"error: {p}\n")
+            else:
+                sys.stderr.write(f"error: {e.message or str(e)}\n")
+        raise typer.Exit(code=2) from None
+    except ClutterError as e:
+        is_lock = e.code == ErrorCode.LOCK_TIMEOUT or "lock" in str(e).lower()
+        exit_code = 5 if is_lock else 3
+        if json_mode:
+            import json
+
+            sys.stdout.write(
+                json.dumps(
+                    {
+                        "schema_version": 1,
+                        "command": command_name or "unknown",
+                        "error": str(e),
+                        "code": exit_code,
+                    }
+                )
+                + "\n"
+            )
+        else:
+            sys.stderr.write(f"error: {e.message or str(e)}\n")
+        raise typer.Exit(code=exit_code) from None
+    except (FileNotFoundError, FileExistsError) as e:
+        if json_mode:
+            import json
+
+            sys.stdout.write(
+                json.dumps(
+                    {
+                        "schema_version": 1,
+                        "command": command_name or "unknown",
+                        "error": str(e),
+                        "code": 2,
+                    }
+                )
+                + "\n"
+            )
+        else:
+            sys.stderr.write(f"error: {e}\n")
+        raise typer.Exit(code=2) from None
+    except Exception as e:
+        logger.exception("Unexpected error during CLI execution: %s", e)
+        if json_mode:
+            import json
+
+            sys.stdout.write(
+                json.dumps(
+                    {
+                        "schema_version": 1,
+                        "command": command_name or "unknown",
+                        "error": str(e),
+                        "code": 1,
+                    }
+                )
+                + "\n"
+            )
+        else:
+            sys.stderr.write(f"error: unexpected error: {e}\n")
+        raise typer.Exit(code=1) from None
+
+
+def error_handler_decorator(func: Callable[P, R]) -> Callable[P, R]:
+    """Decorator version of handle_errors for Typer commands."""
+
+    @functools.wraps(func)
+    def wrapper(*args: P.args, **kwargs: P.kwargs) -> R:
+        json_mode = bool(kwargs.get("json_output", False))
+        with handle_errors(json_mode=json_mode, command_name=func.__name__):
+            return func(*args, **kwargs)
+
+    return wrapper
+
+
+__all__ = ["error_handler_decorator", "exit_with_code", "handle_errors"]