clutterxp 1.1.0__py3-none-any.whl

clutterxp/__init__.py

@@ -0,0 +1,4 @@
+"""ClutterXP - configurable, safe, fast file organizer."""
+
+__version__ = "1.1.0"
+

clutterxp/cli/__init__.py

@@ -0,0 +1,7 @@
+"""ClutterXP command-line interface package."""
+
+from __future__ import annotations
+
+from .app import app, build_organizer, cxp_main, main
+
+__all__ = ["app", "build_organizer", "cxp_main", "main"]

clutterxp/cli/app.py

@@ -0,0 +1,251 @@
+"""Typer root application, global option parsing, dependency wiring, and entry points."""
+
+from __future__ import annotations
+
+import logging
+import os
+import sys
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Annotated
+
+import typer
+
+from clutterxp import logging_setup, paths, safety
+from clutterxp.cli.cmd_config import config_app
+from clutterxp.cli.cmd_doctor import doctor_command
+from clutterxp.cli.cmd_duplicates import duplicates_app
+from clutterxp.cli.cmd_gui import gui_command
+from clutterxp.cli.cmd_history import history_app
+from clutterxp.cli.cmd_init import init_command
+from clutterxp.cli.cmd_organize import organize_command
+from clutterxp.cli.cmd_rules import rules_app
+from clutterxp.cli.cmd_scan import scan_command
+from clutterxp.cli.cmd_service import service_app
+from clutterxp.cli.cmd_undo import undo_command
+from clutterxp.cli.cmd_watch import watch_command
+from clutterxp.cli.errors import handle_errors
+from clutterxp.config import loader
+from clutterxp.history.service import HistoryService
+from clutterxp.history.undo import UndoService
+from clutterxp.models import ClutterError, ConfigError, ErrorCode, SafetyRefusal
+from clutterxp.mover.safe_move import SafeMover
+from clutterxp.organizer import OrganizerImpl
+from clutterxp.rules import build_engine
+
+logger = logging.getLogger("clutterxp.cli")
+
+
+@dataclass(frozen=True, slots=True)
+class GlobalOptions:
+    """Parsed global command-line options passed down through Typer context."""
+
+    config: Path | None
+    json_mode: bool
+    quiet: bool
+    verbose: int
+    no_color: bool
+    allow_root: bool
+
+
+def get_globals(ctx: typer.Context) -> GlobalOptions:
+    """Retrieve GlobalOptions from Typer context or fallback to defaults."""
+    if ctx.obj is not None and isinstance(ctx.obj, GlobalOptions):
+        return ctx.obj
+    obj = ctx.find_object(GlobalOptions)
+    if obj is not None:
+        return obj
+    return GlobalOptions(
+        config=None,
+        json_mode=False,
+        quiet=False,
+        verbose=0,
+        no_color=False,
+        allow_root=False,
+    )
+
+
+def version_callback(value: bool) -> None:
+    """Print version and exit cleanly."""
+    if value:
+        try:
+            from clutterxp import __version__
+
+            ver = __version__
+        except Exception:
+            ver = "1.0.0"
+        typer.echo(f"clutterxp {ver}")
+        raise typer.Exit(code=0)
+
+
+def build_organizer(config_path: Path | None = None) -> OrganizerImpl:
+    """Wire dependencies and build an OrganizerImpl facade."""
+    resolved_config_path = config_path if config_path is not None else paths.config_path()
+    runtime_cfg = loader.load(resolved_config_path)
+
+    engine = build_engine(
+        list(runtime_cfg.rules),
+        runtime_cfg.settings,
+        watch=list(runtime_cfg.watch_entries),
+    )
+    mover = SafeMover(verify_copy=runtime_cfg.settings.verify_copy)
+    history = HistoryService(paths.history_db_path())
+    undo_svc = UndoService(history, mover, paths.fs_lock_path())
+
+    return OrganizerImpl(
+        runtime_cfg,
+        engine,
+        mover,
+        history,
+        undo_service=undo_svc,
+        fs_lock_path=paths.fs_lock_path(),
+    )
+
+
+# Root application with completion support
+app = typer.Typer(
+    name="clutterxp",
+    help="ClutterXP: Configurable, safe, fast file organizer.",
+    no_args_is_help=True,
+    add_completion=True,
+)
+
+
+@app.callback(no_args_is_help=True)
+def main_callback(
+    ctx: typer.Context,
+    config: Annotated[
+        Path | None,
+        typer.Option(
+            "--config",
+            "-c",
+            envvar="CLUTTERXP_CONFIG",
+            help="Path to configuration file",
+        ),
+    ] = None,
+    json_output: Annotated[
+        bool,
+        typer.Option(
+            "--json",
+            help="Machine-readable JSON output (schema_version: 1); no colors, no prompts",
+        ),
+    ] = False,
+    quiet: Annotated[
+        bool,
+        typer.Option(
+            "-q",
+            "--quiet",
+            help="Quiet output (errors and results only)",
+        ),
+    ] = False,
+    verbose: Annotated[
+        int,
+        typer.Option(
+            "-v",
+            "--verbose",
+            count=True,
+            help="Increase logging verbosity (-v for INFO, -vv for DEBUG)",
+        ),
+    ] = 0,
+    no_color: Annotated[
+        bool,
+        typer.Option(
+            "--no-color",
+            help="Disable colors (also honors NO_COLOR environment variable)",
+        ),
+    ] = False,
+    allow_root: Annotated[
+        bool,
+        typer.Option(
+            "--allow-root",
+            help="Permit running as root user (otherwise refused for safety)",
+        ),
+    ] = False,
+    version: Annotated[
+        bool | None,
+        typer.Option(
+            "--version",
+            callback=version_callback,
+            is_eager=True,
+            help="Show ClutterXP version",
+        ),
+    ] = None,
+) -> None:
+    """ClutterXP root callback setting up globals, logging, and safety checks."""
+    effective_no_color = no_color or bool(os.environ.get("NO_COLOR", "").strip())
+    ctx.obj = GlobalOptions(
+        config=config,
+        json_mode=json_output,
+        quiet=quiet,
+        verbose=verbose,
+        no_color=effective_no_color,
+        allow_root=allow_root,
+    )
+
+    # Invariant S10: refuse root execution unless --allow-root
+    with handle_errors(json_mode=json_output, command_name="root"):
+        safety.refuse_root(allow_root=allow_root)
+
+    # Setup logging
+    log_level = 0
+    if quiet:
+        log_level = 0
+    elif verbose > 0:
+        log_level = verbose
+    logging_setup.setup_logging(verbosity=log_level)
+
+
+# Register subcommands and command groups
+app.command("init")(init_command)
+app.add_typer(config_app, name="config")
+app.add_typer(rules_app, name="rules")
+app.command("scan")(scan_command)
+app.command("organize")(organize_command)
+app.command("watch")(watch_command)
+app.add_typer(history_app, name="history")
+app.command("undo")(undo_command)
+app.add_typer(duplicates_app, name="duplicates")
+app.add_typer(service_app, name="service")
+app.command("doctor")(doctor_command)
+app.command("gui")(gui_command)
+
+
+def main() -> None:
+    """CLI entry point for clutterxp binary."""
+    try:
+        app()
+    except SafetyRefusal as e:
+        sys.stderr.write(f"error: {e}\n")
+        sys.exit(4)
+    except ConfigError as e:
+        if e.problems:
+            for p in e.problems:
+                sys.stderr.write(f"error: {p}\n")
+        else:
+            sys.stderr.write(f"error: {e}\n")
+        sys.exit(2)
+    except ClutterError as e:
+        code = 5 if e.code == ErrorCode.LOCK_TIMEOUT or "lock" in str(e).lower() else 3
+        sys.stderr.write(f"error: {e}\n")
+        sys.exit(code)
+    except SystemExit:
+        raise
+    except Exception as e:
+        logger.exception("Unexpected error")
+        sys.stderr.write(f"error: unexpected error: {e}\n")
+        sys.exit(1)
+
+
+def cxp_main() -> None:
+    """CLI entry point for cxp binary alias."""
+    main()
+
+
+__all__ = [
+    "GlobalOptions",
+    "app",
+    "build_organizer",
+    "cxp_main",
+    "get_globals",
+    "main",
+]

clutterxp/cli/cmd_config.py

@@ -0,0 +1,250 @@
+"""Command handlers for `clutterxp config` subcommands."""
+
+from __future__ import annotations
+
+import contextlib
+import os
+import shutil
+import subprocess
+import sys
+import tempfile
+from pathlib import Path
+from typing import TYPE_CHECKING, Annotated
+
+import typer
+
+from clutterxp import paths
+from clutterxp.cli.errors import handle_errors
+from clutterxp.cli.render import get_console, print_json, safe_str
+from clutterxp.config import jsonschema, loader
+from clutterxp.models import ConfigError
+
+if TYPE_CHECKING:
+    from clutterxp.cli.app import GlobalOptions
+
+config_app = typer.Typer(
+    help="Manage ClutterXP configuration (path, show, validate, schema, edit, migrate)",
+    no_args_is_help=True,
+)
+
+
+@config_app.command("path")
+def config_path_command(ctx: typer.Context) -> None:
+    """Print the resolved path to config.yaml."""
+    from clutterxp.cli.app import get_globals
+
+    opts: GlobalOptions = get_globals(ctx)
+    target = opts.config if opts.config is not None else paths.config_path()
+
+    with handle_errors(json_mode=opts.json_mode, command_name="config_path"):
+        if opts.json_mode:
+            print_json(
+                {
+                    "schema_version": 1,
+                    "command": "config_path",
+                    "path": safe_str(target),
+                    "exists": target.exists(),
+                }
+            )
+        else:
+            console = get_console(no_color=opts.no_color)
+            console.print(safe_str(target))
+
+
+@config_app.command("show")
+def config_show_command(ctx: typer.Context) -> None:
+    """Print effective configuration settings with paths expanded."""
+    from clutterxp.cli.app import get_globals
+
+    opts: GlobalOptions = get_globals(ctx)
+    target = opts.config if opts.config is not None else paths.config_path()
+
+    with handle_errors(json_mode=opts.json_mode, command_name="config_show"):
+        cfg = loader.load(target)
+
+        if opts.json_mode:
+            print_json(
+                {
+                    "schema_version": 1,
+                    "command": "config_show",
+                    "config_path": safe_str(target),
+                    "version": 1,
+                    "settings": cfg.settings.model_dump(),
+                    "watch": [w.model_dump() for w in cfg.watch_entries],
+                    "rules": [r.model_dump() for r in cfg.all_rules],
+                    "is_valid": cfg.is_valid,
+                    "errors": list(cfg.errors),
+                    "warnings": list(cfg.warnings),
+                }
+            )
+        else:
+            console = get_console(no_color=opts.no_color)
+            console.print(f"[bold]Configuration file:[/bold] {safe_str(target)}\n")
+            console.print(f"[bold]Settings:[/bold] {cfg.settings.model_dump()}\n")
+            console.print(f"[bold]Watch Folders ({len(cfg.watch_entries)}):[/bold]")
+            for w in cfg.watch_entries:
+                console.print(f"  - {safe_str(w.path)} (recursive={w.recursive})")
+            console.print(f"\n[bold]Rules ({len(cfg.all_rules)}):[/bold]")
+            for r in cfg.all_rules:
+                status = "enabled" if r.enabled else "disabled"
+                dest_str = safe_str(r.destination)
+                console.print(
+                    f"  - {safe_str(r.name)} [{status}, priority={r.priority}] -> {dest_str}"
+                )
+
+
+@config_app.command("validate")
+def config_validate_command(
+    ctx: typer.Context,
+    strict: Annotated[
+        bool,
+        typer.Option(
+            "--strict",
+            help="Treat warnings as errors (exit code 3)",
+        ),
+    ] = False,
+) -> None:
+    """Validate configuration file and print errors/warnings with YAML paths."""
+    from clutterxp.cli.app import get_globals
+
+    opts: GlobalOptions = get_globals(ctx)
+    target = opts.config if opts.config is not None else paths.config_path()
+
+    with handle_errors(json_mode=opts.json_mode, command_name="config_validate"):
+        cfg = loader.load(target)
+
+        is_valid = len(cfg.errors) == 0 and (not strict or len(cfg.warnings) == 0)
+
+        if opts.json_mode:
+            print_json(
+                {
+                    "schema_version": 1,
+                    "command": "config_validate",
+                    "config_path": safe_str(target),
+                    "valid": is_valid,
+                    "errors": list(cfg.errors),
+                    "warnings": list(cfg.warnings),
+                }
+            )
+        else:
+            console = get_console(no_color=opts.no_color)
+            for err in cfg.errors:
+                console.print(f"error: {err}")
+            for warn in cfg.warnings:
+                console.print(f"warning: {warn}")
+
+            if is_valid and not cfg.errors and not cfg.warnings:
+                console.print("Configuration is valid.")
+
+        if cfg.errors:
+            raise typer.Exit(code=2)
+        if strict and cfg.warnings:
+            raise typer.Exit(code=3)
+
+
+@config_app.command("schema")
+def config_schema_command(ctx: typer.Context) -> None:
+    """Print the JSON Schema for configuration files."""
+    from clutterxp.cli.app import get_globals
+
+    opts: GlobalOptions = get_globals(ctx)
+    with handle_errors(json_mode=opts.json_mode, command_name="config_schema"):
+        schema = jsonschema.config_json_schema()
+        print_json(schema)
+
+
+@config_app.command("edit")
+def config_edit_command(ctx: typer.Context) -> None:
+    """Open $EDITOR on a temp copy, validate on exit, replace atomically if valid."""
+    from clutterxp.cli.app import get_globals
+
+    opts: GlobalOptions = get_globals(ctx)
+    target = opts.config if opts.config is not None else paths.config_path()
+
+    with handle_errors(json_mode=opts.json_mode, command_name="config_edit"):
+        if not target.exists():
+            sys.stderr.write(f"error: Config file not found at '{target}'. Run `init` first.\n")
+            raise typer.Exit(code=2)
+
+        # Create temporary working copy in same directory
+        temp_fd, temp_path_str = tempfile.mkstemp(
+            dir=target.parent, prefix=f".{target.name}.", suffix=".edit.tmp"
+        )
+        temp_path = Path(temp_path_str)
+        try:
+            with os.fdopen(temp_fd, "wb") as f_out, target.open("rb") as f_in:
+                shutil.copyfileobj(f_in, f_out)
+
+            editor = os.environ.get("EDITOR")
+            if not editor:
+                editor = "nano" if shutil.which("nano") else "vi"
+
+            res = subprocess.run([editor, str(temp_path)], check=False)  # noqa: S603
+            if res.returncode != 0:
+                sys.stderr.write(f"error: Editor exited with code {res.returncode}\n")
+                raise typer.Exit(code=2)
+
+            # Validate the edited file
+            try:
+                cfg = loader.load(temp_path)
+                if not cfg.is_valid:
+                    sys.stderr.write("error: Validation failed for edited configuration:\n")
+                    for err in cfg.errors:
+                        sys.stderr.write(f"  {err}\n")
+                    sys.stderr.write("Changes discarded.\n")
+                    raise typer.Exit(code=2)
+            except ConfigError as ce:
+                sys.stderr.write(
+                    f"error: Failed to load edited configuration: {ce}\nChanges discarded.\n"
+                )
+                raise typer.Exit(code=2) from None
+
+            # Backup existing and replace atomically
+            bak_path = target.with_name(target.name + ".bak")
+            shutil.copy2(target, bak_path)
+            with contextlib.suppress(OSError):
+                bak_path.chmod(0o600)
+
+            temp_path.chmod(0o600)
+            temp_path.replace(target)
+
+            if opts.json_mode:
+                print_json(
+                    {
+                        "schema_version": 1,
+                        "command": "config_edit",
+                        "status": "updated",
+                        "path": safe_str(target),
+                    }
+                )
+            else:
+                console = get_console(no_color=opts.no_color)
+                console.print(f"Configuration successfully updated: {safe_str(target)}")
+        finally:
+            if temp_path.exists():
+                with contextlib.suppress(OSError):
+                    temp_path.unlink()
+
+
+@config_app.command("migrate")
+def config_migrate_command(ctx: typer.Context) -> None:
+    """Migrate configuration file if necessary (v1 is current)."""
+    from clutterxp.cli.app import get_globals
+
+    opts: GlobalOptions = get_globals(ctx)
+    with handle_errors(json_mode=opts.json_mode, command_name="config_migrate"):
+        if opts.json_mode:
+            print_json(
+                {
+                    "schema_version": 1,
+                    "command": "config_migrate",
+                    "status": "up_to_date",
+                    "version": 1,
+                }
+            )
+        else:
+            console = get_console(no_color=opts.no_color)
+            console.print("Configuration is up to date (version 1).")
+
+
+__all__ = ["config_app"]