clutterxp 1.1.0__py3-none-any.whl

clutterxp/cli/cmd_gui.py

@@ -0,0 +1,22 @@
+"""Command handler for `clutterxp gui`."""
+
+from __future__ import annotations
+
+import importlib
+import sys
+
+import typer
+
+
+def gui_command(ctx: typer.Context) -> None:
+    """Launch the graphical interface (v1.1 feature)."""
+    try:
+        importlib.import_module("PySide6")
+        gui_app = importlib.import_module("clutterxp.gui.app")
+        gui_app.main()
+    except (ImportError, ModuleNotFoundError, AttributeError):
+        sys.stderr.write('Install GUI support with: pip install "clutterxp[gui]"\n')
+        raise typer.Exit(code=1) from None
+
+
+__all__ = ["gui_command"]

clutterxp/cli/cmd_history.py

@@ -0,0 +1,233 @@
+"""Command handlers for `clutterxp history` subcommands."""
+
+from __future__ import annotations
+
+import sys
+from datetime import datetime, timedelta, timezone
+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,
+    render_history_table,
+    safe_str,
+)
+from clutterxp.history.service import HistoryService, op_to_dict
+from clutterxp.models import OpStatus
+from clutterxp.units import parse_duration_seconds
+
+if TYPE_CHECKING:
+    from clutterxp.cli.app import GlobalOptions
+
+history_app = typer.Typer(
+    help="Inspect and maintain file operation history",
+    invoke_without_command=True,
+)
+
+
+@history_app.callback(invoke_without_command=True)
+def history_list_command(
+    ctx: typer.Context,
+    limit: Annotated[
+        int,
+        typer.Option("--limit", "-l", help="Maximum records to return"),
+    ] = 50,
+    batch: Annotated[
+        int | None,
+        typer.Option("--batch", "-b", help="Filter by batch ID"),
+    ] = None,
+    status: Annotated[
+        str | None,
+        typer.Option(
+            "--status",
+            "-s",
+            help="Filter by status (done, undone, failed, pending)",
+        ),
+    ] = None,
+    since: Annotated[
+        str | None,
+        typer.Option(
+            "--since",
+            help="Filter operations since duration (e.g. '7d') or ISO timestamp",
+        ),
+    ] = None,
+    rule: Annotated[
+        str | None,
+        typer.Option("--rule", help="Filter by rule name"),
+    ] = None,
+    path: Annotated[
+        str | None,
+        typer.Option("--path", help="Filter by path substring"),
+    ] = None,
+) -> None:
+    """List file operations from the history journal."""
+    if ctx.invoked_subcommand is not None:
+        return
+
+    from clutterxp.cli.app import get_globals
+
+    opts: GlobalOptions = get_globals(ctx)
+    db_path = paths.history_db_path()
+
+    with handle_errors(json_mode=opts.json_mode, command_name="history"):
+        history = HistoryService(db_path)
+
+        op_status = None
+        if status:
+            try:
+                op_status = OpStatus(status.lower())
+            except ValueError:
+                sys.stderr.write(
+                    f"error: Invalid status '{status}'. Choices: done, undone, failed, pending\n"
+                )
+                raise typer.Exit(code=2) from None
+
+        since_iso = None
+        if since:
+            try:
+                secs = parse_duration_seconds(since)
+                dt = datetime.now(timezone.utc) - timedelta(seconds=secs)
+                since_iso = dt.isoformat()
+            except Exception:
+                since_iso = since
+
+        records = history.list_ops(
+            batch_id=batch,
+            status=op_status,
+            limit=limit,
+            since_iso=since_iso,
+            rule_name=rule,
+            path_contains=path,
+        )
+
+        if opts.json_mode:
+            ops_json = [op_to_dict(r) for r in records]
+            print_json({"schema_version": 1, "operations": ops_json})
+        else:
+            if not records:
+                get_console(no_color=opts.no_color).print("No history operations found.")
+            else:
+                render_history_table(records, no_color=opts.no_color)
+
+
+@history_app.command("show")
+def history_show_command(
+    ctx: typer.Context,
+    op_id: Annotated[int, typer.Argument(help="Operation ID to inspect")],
+) -> None:
+    """Show details of a specific operation and its related events."""
+    from clutterxp.cli.app import get_globals
+
+    opts: GlobalOptions = get_globals(ctx)
+    db_path = paths.history_db_path()
+
+    with handle_errors(json_mode=opts.json_mode, command_name="history_show"):
+        history = HistoryService(db_path)
+        op = history.get_op(op_id)
+        if op is None:
+            sys.stderr.write(f"error: Operation ID {op_id} not found in history\n")
+            raise typer.Exit(code=2)
+
+        events = history.event_list(op_id=op_id)
+
+        if opts.json_mode:
+            print_json(
+                {
+                    "schema_version": 1,
+                    "command": "history_show",
+                    "operation": op_to_dict(op),
+                    "events": events,
+                }
+            )
+        else:
+            console = get_console(no_color=opts.no_color)
+            console.print(f"[bold]Operation #{op.id}[/bold]")
+            console.print(f"  Batch:       {op.batch_id}")
+            console.print(f"  Status:      {op.status.value}")
+            console.print(f"  Rule:        {op.rule_name or '(none)'}")
+            console.print(f"  Strategy:    {op.strategy.value if op.strategy else '(none)'}")
+            console.print(f"  Source:      {safe_str(op.src_path)}")
+            console.print(f"  Destination: {safe_str(op.dst_path or '(none)')}")
+            console.print(f"  Size:        {op.size} bytes")
+            console.print(f"  SHA-256:     {op.sha256 or '(none)'}")
+            console.print(f"  Created:     {op.created_at}")
+            console.print(f"  Finished:    {op.finished_at or '(none)'}")
+            console.print(f"  Undone:      {op.undone_at or '(none)'}")
+            if op.error:
+                console.print(f"  Error:       {op.error}")
+            if events:
+                console.print(f"\n[bold]Events ({len(events)}):[/bold]")
+                for ev in events:
+                    lvl = ev.get("level", "info").upper()
+                    ts = ev.get("timestamp")
+                    msg = ev.get("message")
+                    console.print(f"  [{lvl}] {ts}: {msg}")
+
+
+@history_app.command("prune")
+def history_prune_command(
+    ctx: typer.Context,
+    older_than: Annotated[
+        str,
+        typer.Option(
+            "--older-than",
+            help="Prune operations older than duration (e.g. 180d)",
+        ),
+    ] = "180d",
+    yes: Annotated[
+        bool,
+        typer.Option(
+            "--yes",
+            "-y",
+            help="Skip confirmation prompt",
+        ),
+    ] = False,
+) -> None:
+    """Prune history operations older than a cutoff (deletes rows only, keeps pending ops)."""
+    from clutterxp.cli.app import get_globals
+
+    opts: GlobalOptions = get_globals(ctx)
+    db_path = paths.history_db_path()
+
+    with handle_errors(json_mode=opts.json_mode, command_name="history_prune"):
+        history = HistoryService(db_path)
+
+        try:
+            secs = parse_duration_seconds(older_than)
+            days = max(1, secs // 86400)
+        except Exception:
+            try:
+                days = int(older_than.rstrip("dD"))
+            except ValueError:
+                sys.stderr.write(f"error: Invalid duration '{older_than}'. Expected e.g. '180d'\n")
+                raise typer.Exit(code=2) from None
+
+        if (
+            not yes
+            and not opts.json_mode
+            and not typer.confirm(f"Prune history records older than {days} days?", default=False)
+        ):
+            get_console(no_color=opts.no_color).print("Aborted.")
+            raise typer.Exit(code=0)
+
+        pruned = history.prune(days)
+
+        if opts.json_mode:
+            print_json(
+                {
+                    "schema_version": 1,
+                    "command": "history_prune",
+                    "older_than_days": days,
+                    "pruned_rows": pruned,
+                }
+            )
+        else:
+            console = get_console(no_color=opts.no_color)
+            console.print(f"Pruned {pruned} history operations older than {days} days.")
+
+
+__all__ = ["history_app"]

clutterxp/cli/cmd_init.py

@@ -0,0 +1,76 @@
+"""Command handler for `clutterxp init`."""
+
+from __future__ import annotations
+
+import sys
+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 writer
+
+if TYPE_CHECKING:
+    from clutterxp.cli.app import GlobalOptions
+
+
+def init_command(
+    ctx: typer.Context,
+    minimal: Annotated[
+        bool,
+        typer.Option(
+            "--minimal",
+            help="Write minimal configuration with Downloads watch only",
+        ),
+    ] = False,
+    force: Annotated[
+        bool,
+        typer.Option(
+            "--force",
+            "-f",
+            help="Overwrite existing configuration file",
+        ),
+    ] = False,
+) -> None:
+    """Initialize a commented config.yaml file with 0600 permissions."""
+    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="init"):
+        if target.exists() and not force:
+            msg = f"Config file already exists at '{target}'. Pass --force to overwrite."
+            if opts.json_mode:
+                print_json(
+                    {
+                        "schema_version": 1,
+                        "command": "init",
+                        "error": msg,
+                        "code": 2,
+                    }
+                )
+            else:
+                sys.stderr.write(f"error: {msg}\n")
+            raise typer.Exit(code=2)
+
+        created_path: Path = writer.init_config(target, minimal=minimal, force=force)
+
+        if opts.json_mode:
+            print_json(
+                {
+                    "schema_version": 1,
+                    "command": "init",
+                    "path": safe_str(created_path),
+                    "status": "created",
+                }
+            )
+        else:
+            console = get_console(no_color=opts.no_color)
+            console.print(f"Created configuration at {safe_str(created_path)} (mode 0600)")
+
+
+__all__ = ["init_command"]

clutterxp/cli/cmd_organize.py

@@ -0,0 +1,226 @@
+"""Command handler for `clutterxp organize`."""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+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,
+    render_organize_summary,
+    render_plan,
+    safe_str,
+)
+from clutterxp.models import (
+    ErrorCode,
+    Plan,
+    PlannedAction,
+    PlanStatus,
+    SafetyRefusal,
+)
+
+if TYPE_CHECKING:
+    from clutterxp.cli.app import GlobalOptions
+
+
+def organize_command(
+    ctx: typer.Context,
+    paths: Annotated[
+        list[Path] | None,
+        typer.Argument(
+            help="Folders or files to organize (defaults to configured watch folders)",
+        ),
+    ] = None,
+    dry_run: Annotated[
+        bool,
+        typer.Option(
+            "-n",
+            "--dry-run",
+            help="Preview actions without moving any files",
+        ),
+    ] = False,
+    yes: Annotated[
+        bool,
+        typer.Option(
+            "-y",
+            "--yes",
+            help="Skip confirmation prompt for moves exceeding confirm_threshold",
+        ),
+    ] = False,
+    recursive: Annotated[
+        bool,
+        typer.Option(
+            "--recursive",
+            "-r",
+            help="Scan directories recursively",
+        ),
+    ] = False,
+    rule: Annotated[
+        list[str] | None,
+        typer.Option(
+            "--rule",
+            help="Limit execution to named rules (repeatable)",
+        ),
+    ] = None,
+    limit: Annotated[
+        int | None,
+        typer.Option(
+            "--limit",
+            "-l",
+            help="Cap maximum number of files to move in this run",
+        ),
+    ] = None,
+    strict: Annotated[
+        bool,
+        typer.Option(
+            "--strict",
+            help="Exit with code 3 if any file is ambiguous or failed",
+        ),
+    ] = False,
+) -> None:
+    """Sort files into destinations according to configured rules."""
+    from clutterxp.cli.app import build_organizer, get_globals
+
+    opts: GlobalOptions = get_globals(ctx)
+
+    with handle_errors(json_mode=opts.json_mode, command_name="organize"):
+        organizer = build_organizer(opts.config)
+        plan = organizer.plan(
+            paths=paths if paths else None,
+            recursive=recursive,
+            only_rules=rule if rule else None,
+        )
+
+        # Apply limit if specified
+        if limit is not None and limit >= 0:
+            move_count = 0
+            limited_actions: list[PlannedAction] = []
+            for a in plan.actions:
+                if a.status in (PlanStatus.WILL_MOVE, PlanStatus.WILL_MOVE_RENAMED):
+                    if move_count < limit:
+                        move_count += 1
+                        limited_actions.append(a)
+                    else:
+                        limited_actions.append(
+                            PlannedAction(
+                                file=a.file,
+                                status=PlanStatus.IGNORED,
+                                decision=a.decision,
+                                code=ErrorCode.NONE,
+                                message="Skipped due to --limit",
+                            )
+                        )
+                else:
+                    limited_actions.append(a)
+            plan = Plan(folders=plan.folders, actions=tuple(limited_actions))
+
+        moves_planned = plan.count(PlanStatus.WILL_MOVE) + plan.count(PlanStatus.WILL_MOVE_RENAMED)
+        ambig_count = plan.count(PlanStatus.AMBIGUOUS)
+
+        # Print plan unless in quiet mode
+        if not opts.quiet and not opts.json_mode:
+            render_plan(
+                plan,
+                dry_run=dry_run,
+                no_color=opts.no_color,
+            )
+
+        # Dry run stops here
+        if dry_run:
+            if opts.json_mode:
+                actions_json = _build_actions_json(plan)
+                print_json(
+                    {
+                        "schema_version": 1,
+                        "command": "organize",
+                        "dry_run": True,
+                        "batch_id": None,
+                        "summary": {
+                            "moved": 0,
+                            "unmatched": plan.count(PlanStatus.NO_MATCH)
+                            + plan.count(PlanStatus.IGNORED),
+                            "ambiguous": ambig_count,
+                            "blocked": plan.count(PlanStatus.BLOCKED),
+                            "failed": 0,
+                        },
+                        "actions": actions_json,
+                    }
+                )
+            if strict and ambig_count > 0:
+                raise typer.Exit(code=3)
+            return
+
+        # Check confirmation threshold
+        threshold = organizer.config.settings.confirm_threshold
+        if organizer.needs_confirmation(plan) and not yes:
+            if not sys.stdin.isatty():
+                raise SafetyRefusal(
+                    f"Refused: confirmation required to move {moves_planned} files "
+                    f"(confirm_threshold={threshold}) in non-interactive session. "
+                    "Pass --yes to confirm."
+                )
+            if not typer.confirm(f"Move {moves_planned} files?", default=True):
+                get_console(no_color=opts.no_color).print("Aborted.")
+                raise typer.Exit(code=0)
+
+        # Apply plan
+        batch_result = organizer.apply(plan, command="organize")
+
+        if opts.json_mode:
+            actions_json = _build_actions_json(plan)
+            print_json(
+                {
+                    "schema_version": 1,
+                    "command": "organize",
+                    "dry_run": False,
+                    "batch_id": batch_result.batch_id,
+                    "summary": {
+                        "moved": batch_result.moved,
+                        "unmatched": plan.count(PlanStatus.NO_MATCH)
+                        + plan.count(PlanStatus.IGNORED),
+                        "ambiguous": ambig_count,
+                        "blocked": batch_result.blocked,
+                        "failed": batch_result.failed,
+                    },
+                    "actions": actions_json,
+                }
+            )
+        else:
+            render_organize_summary(plan, batch_result, no_color=opts.no_color)
+
+        # Exit code: 3 on partial failure or strict with ambiguity
+        if batch_result.blocked > 0 or batch_result.failed > 0:
+            raise typer.Exit(code=3)
+        if strict and ambig_count > 0:
+            raise typer.Exit(code=3)
+
+
+def _build_actions_json(plan: Plan) -> list[dict[str, Any]]:
+    """Build list of action dictionaries for JSON output."""
+    actions_json: list[dict[str, Any]] = []
+    for a in plan.actions:
+        status_str = a.status.value
+        act_data: dict[str, Any] = {
+            "status": status_str,
+            "src": safe_str(a.file.path),
+        }
+        if a.dest_path is not None:
+            act_data["dst"] = safe_str(a.dest_path)
+        if a.decision.hit is not None:
+            act_data["rule"] = a.decision.hit.rule_name
+            act_data["matched_by"] = a.decision.hit.matched_by
+        if a.decision.candidates:
+            act_data["candidates"] = [c.rule_name for c in a.decision.candidates]
+        if a.status == PlanStatus.BLOCKED:
+            act_data["code"] = a.code.value
+            act_data["message"] = a.message or a.code.value
+        actions_json.append(act_data)
+    return actions_json
+
+
+__all__ = ["organize_command"]