fs-tool-cli 0.1.2__py3-none-any.whl

fs_tool/__init__.py

@@ -0,0 +1,9 @@
+"""fs-tool – lightweight, secure and agent-friendly filesystem CLI."""
+
+from importlib.metadata import PackageNotFoundError
+from importlib.metadata import version as _distribution_version
+
+try:
+    __version__ = _distribution_version("fs-tool-cli")
+except PackageNotFoundError:
+    __version__ = "0.1.0"

fs_tool/__main__.py

@@ -0,0 +1,8 @@
+"""Allow running the package as ``python -m fs_tool``."""
+
+import sys
+
+from fs_tool.cli import main
+
+if __name__ == "__main__":
+    sys.exit(main())

fs_tool/cli.py

@@ -0,0 +1,305 @@
+"""Command-line interface for fs-tool.
+
+Console script entry point: ``fs_tool.cli:main`` (``fs-tool``).
+The package is also runnable as ``python -m fs_tool``.
+"""
+
+from __future__ import annotations
+
+import sys
+from dataclasses import asdict
+from pathlib import Path
+
+import typer
+from click.exceptions import ClickException
+from click.exceptions import Exit as ClickExit
+
+from fs_tool import __version__
+from fs_tool.core.config import load_config
+from fs_tool.core.errors import ErrorCode, FsToolError
+from fs_tool.core.traversal import traverse
+from fs_tool.output.json import SCHEMA_VERSION, Envelope, Error
+from fs_tool.safety.validation import validate_path
+
+# Process exit codes (plan.md section 4.3).
+EXIT_SUCCESS = 0
+EXIT_FAILURE = 1
+EXIT_INVALID_ARGS = 2
+EXIT_ACCESS_DENIED = 3
+EXIT_CONFLICT = 4
+EXIT_INCOMPLETE = 5
+
+app = typer.Typer(
+    name="fs-tool",
+    help="Inspect, analyze, compare and organize local filesystems.",
+    no_args_is_help=True,
+    context_settings={"help_option_names": ["-h", "--help"]},
+)
+
+
+class CliContext:
+    """Shared CLI context populated by the root callback."""
+
+    def __init__(
+        self,
+        allow_root: list[str],
+        config: str | None,
+        output_format: str,
+        json_output: bool,
+        plain_output: bool,
+    ) -> None:
+        self.allow_root = allow_root
+        self.config = config
+        self.output_format = output_format
+        self.json_output = json_output
+        self.plain_output = plain_output
+
+
+def _resolve_format(
+    format_value: str,
+    json_output: bool,
+    plain_output: bool,
+    is_tty: bool,
+) -> str:
+    """Resolve the effective output format (plan.md decision D7).
+
+    Precedence: explicit --json/--plain > --format > auto (TTY -> plain,
+    otherwise JSON). ``--json`` and ``--plain`` are mutually exclusive.
+    """
+    if json_output and plain_output:
+        raise FsToolError(
+            "--json and --plain are mutually exclusive.",
+            code=ErrorCode.INVALID_ARGUMENT,
+        )
+    if json_output:
+        return "json"
+    if plain_output:
+        return "plain"
+    if format_value not in ("auto", "json", "plain"):
+        raise FsToolError(
+            f"Unknown --format value {format_value!r}; use auto, json or plain.",
+            code=ErrorCode.INVALID_ARGUMENT,
+        )
+    if format_value == "auto":
+        return "plain" if is_tty else "json"
+    return format_value
+
+
+def merge_globals(
+    ctx: typer.Context,
+    *,
+    allow_root: list[str] | None = None,
+    config: str | None = None,
+    format_value: str | None = None,
+    json_output: bool | None = None,
+    plain_output: bool | None = None,
+    version: bool = False,
+) -> None:
+    """Merge subcommand-level global options into the CLI context.
+
+    The root callback has already populated the context from root-level
+    options; subcommand-level options override them. The configuration
+    may only restrict allowed roots, never expand them (decision D4).
+    """
+    if version:
+        typer.echo(f"fs-tool {__version__}")
+        raise typer.Exit(EXIT_SUCCESS)
+
+    if config is not None:
+        ctx.obj.config = config
+    if allow_root is not None:
+        # Re-resolve the config with the subcommand's CLI roots.
+        config_obj = load_config(
+            config_path=ctx.obj.config, cli_roots=tuple(Path(root) for root in allow_root)
+        )
+        ctx.obj.allow_root = [str(root) for root in config_obj.allowed_roots]
+    if format_value is not None:
+        ctx.obj.output_format = format_value
+    if json_output is not None:
+        ctx.obj.json_output = json_output
+    if plain_output is not None:
+        ctx.obj.plain_output = plain_output
+
+    if ctx.obj.json_output and ctx.obj.plain_output:
+        raise FsToolError(
+            "--json and --plain are mutually exclusive.",
+            code=ErrorCode.INVALID_ARGUMENT,
+        )
+    ctx.obj.output_format = _resolve_format(
+        ctx.obj.output_format,
+        ctx.obj.json_output,
+        ctx.obj.plain_output,
+        sys.stdout.isatty(),
+    )
+
+
+@app.callback()
+def _root(
+    ctx: typer.Context,
+    allow_root: list[str] = typer.Option(
+        [],
+        "--allow-root",
+        help="Set an allowed root, replacing the default Home and CWD roots (repeatable).",
+    ),
+    config: str | None = typer.Option(None, "--config", help="Path to TOML configuration file."),
+    format_value: str = typer.Option(
+        "auto", "--format", help="Output format: auto, json or plain."
+    ),
+    json_output: bool = typer.Option(False, "--json", help="Explicitly request JSON output."),
+    plain_output: bool = typer.Option(
+        False, "--plain", help="Human-readable output instead of JSON."
+    ),
+    version: bool = typer.Option(False, "--version", help="Show application version and exit."),
+) -> None:
+    """Root callback: global options and version information.
+
+    ``--help``/``--version`` are documented exceptions to the JSON
+    envelope (plan.md section 4.3).
+    """
+    ctx.obj = CliContext(
+        allow_root=[],
+        config=None,
+        output_format="auto",
+        json_output=False,
+        plain_output=False,
+    )
+    merge_globals(
+        ctx,
+        allow_root=list(allow_root),
+        config=config,
+        format_value=format_value,
+        json_output=json_output,
+        plain_output=plain_output,
+        version=version,
+    )
+
+
+# Command groups are registered without commands in Phase 0; commands
+# are implemented in later phases.
+inspect_group = typer.Typer(name="inspect", help="Inspect the filesystem.", no_args_is_help=True)
+find_group = typer.Typer(name="find", help="Find filesystem entries.", no_args_is_help=True)
+duplicates_group = typer.Typer(
+    name="duplicates", help="Find duplicate files.", no_args_is_help=True
+)
+compare_group = typer.Typer(name="compare", help="Compare directory trees.", no_args_is_help=True)
+verify_group = typer.Typer(name="verify", help="Verify filesystem state.", no_args_is_help=True)
+write_group = typer.Typer(name="write", help="Write operations.", no_args_is_help=True)
+
+for group in (
+    inspect_group,
+    find_group,
+    duplicates_group,
+    compare_group,
+    verify_group,
+    write_group,
+):
+    app.add_typer(group)
+
+
+@inspect_group.command(name="tree")
+def inspect_tree(
+    ctx: typer.Context,
+    source: Path = typer.Argument(..., help="Directory to traverse."),
+    max_depth: int | None = typer.Option(None, "--max-depth", help="Maximum recursion depth."),
+    max_entries: int | None = typer.Option(
+        None, "--max-entries", help="Maximum number of entries."
+    ),
+    dirs_only: bool = typer.Option(False, "--dirs-only", help="Directory entries only."),
+    ignore_dir: list[str] = typer.Option(
+        [],
+        "--ignore-dir",
+        help="Ignore a directory by name (repeatable).",
+    ),
+    ignore_pattern: list[str] = typer.Option(
+        [],
+        "--ignore-pattern",
+        help="Ignore names matching a pattern (repeatable).",
+    ),
+) -> int:
+    """Display a directory tree (JSON by default, plain with --plain).
+
+    Global options such as ``--plain`` and ``--allow-root`` precede
+    the command, e.g. ``fs-tool --plain inspect tree /tmp``.
+    """
+    root = validate_path(source, tuple(ctx.obj.allow_root))
+    result = traverse(
+        root,
+        max_depth=max_depth,
+        max_entries=max_entries,
+        dirs_only=dirs_only,
+        ignore_dirs=frozenset(ignore_dir),
+        ignore_patterns=tuple(ignore_pattern),
+    )
+
+    if ctx.obj.output_format == "plain":
+        from fs_tool.output.plain import render_tree
+
+        typer.echo(render_tree(result.entries, root))
+        if not result.complete:
+            print("fs-tool: error: scan incomplete", file=sys.stderr)
+        for error in result.errors:
+            print(
+                f"fs-tool: error: {error.message} ({error.path})",
+                file=sys.stderr,
+            )
+        return EXIT_INCOMPLETE if not result.complete else EXIT_SUCCESS
+
+    entry_dicts = [asdict(entry) for entry in result.entries]
+    errors = tuple(
+        Error(code="INACCESSIBLE_ENTRY", message=error.message, path=error.path)
+        for error in result.errors
+    )
+    envelope = Envelope(
+        schema_version=SCHEMA_VERSION,
+        success=result.complete,
+        command="inspect.tree",
+        result={
+            "root": str(root),
+            "entries": entry_dicts,
+            "count": len(entry_dicts),
+        },
+        errors=errors,
+        complete=result.complete,
+    )
+    typer.echo(envelope.to_json())
+    return EXIT_INCOMPLETE if not result.complete else EXIT_SUCCESS
+
+
+def main(argv: list[str] | None = None) -> int:
+    """Application entry point.
+
+    Returns a process exit code (plan.md section 4.3):
+
+    * 0 - success
+    * 1 - operation failed or verification discrepancies
+    * 2 - invalid arguments or incomplete analysis
+    * 3 - access denied or safety restriction
+    * 4 - operation conflict
+    * 5 - incomplete scan or verification
+    """
+    args = list(sys.argv[1:] if argv is None else argv)
+
+    # ``--version`` is handled up front: typer only invokes the root
+    # callback when a subcommand is selected
+    # (invoke_without_command=False), so the option callback would never
+    # run for ``fs-tool --version``. --help/--version are documented
+    # exceptions to the JSON envelope (plan.md section 4.3).
+    if "--version" in args:
+        print(f"fs-tool {__version__}")
+        return EXIT_SUCCESS
+
+    try:
+        result = app(args=args, standalone_mode=False)
+    except FsToolError as exc:
+        print(f"Error: {exc.message}", file=sys.stderr)
+        return exc.exit_code
+    except ClickExit as exc:
+        return exc.exit_code if isinstance(exc.exit_code, int) else EXIT_SUCCESS
+    except ClickException as exc:
+        # Invalid usage (unknown command, bad option, ...): exit 2.
+        exc.show()
+        return exc.exit_code if isinstance(exc.exit_code, int) else EXIT_FAILURE
+    except Exception as exc:  # CLI boundary: report, do not swallow silently
+        print(f"Unexpected error: {exc}", file=sys.stderr)
+        return EXIT_FAILURE
+    return result if isinstance(result, int) else EXIT_SUCCESS

fs_tool/core/__init__.py

@@ -0,0 +1 @@
+"""Filesystem core: models, safety, traversal, hashing, metadata."""

fs_tool/core/config.py

@@ -0,0 +1,117 @@
+"""TOML configuration loading (plan.md Phase 1, P1-T14, decision D4).
+
+Configuration file: ``$XDG_CONFIG_HOME/fs-tool/config.toml``, overridden
+by ``--config PATH``. There is no automatic loading of project-local
+configuration files. Precedence is CLI > Config > Defaults; the
+configuration may only restrict the allowed roots, never expand them.
+
+Example config file:
+
+.. code-block:: toml
+
+   [fs-tool]
+   allowed_roots = ["/home/user", "/mnt/nas"]
+"""
+
+from __future__ import annotations
+
+import os
+import tomllib
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+from fs_tool.core.errors import ErrorCode, FsToolError
+
+CONFIG_FILE_NAME = "config.toml"
+CONFIG_DIR_NAME = "fs-tool"
+
+
+class ConfigError(FsToolError):
+    """A configuration file could not be read or interpreted."""
+
+    def __init__(self, message: str, path: str | Path | None = None) -> None:
+        super().__init__(
+            message,
+            code=ErrorCode.INVALID_ARGUMENT,
+            path=str(path) if path is not None else None,
+        )
+
+
+@dataclass(frozen=True)
+class AppConfig:
+    """Resolved application configuration.
+
+    ``allowed_roots`` is the effective set of roots after applying CLI
+    > Config > Defaults precedence. The configuration may only restrict
+    roots; it never expands them.
+    """
+
+    allowed_roots: tuple[Path, ...]
+
+
+def _default_config_path() -> Path:
+    xdg_config_home = os.environ.get("XDG_CONFIG_HOME")
+    base = Path(xdg_config_home) if xdg_config_home else Path.home() / ".config"
+    return base / CONFIG_DIR_NAME / CONFIG_FILE_NAME
+
+
+def _config_allowed_roots(data: dict[str, Any]) -> tuple[Path, ...] | None:
+    fs_tool = data.get("fs-tool")
+    if not isinstance(fs_tool, dict):
+        return None
+    roots = fs_tool.get("allowed_roots")
+    if roots is None:
+        return None
+    if not isinstance(roots, list) or not all(isinstance(r, str) for r in roots):
+        raise ConfigError("fs-tool.allowed_roots must be a list of strings")
+    return tuple(Path(root) for root in roots)
+
+
+def load_config(
+    config_path: str | Path | None = None,
+    cli_roots: tuple[Path, ...] | None = None,
+) -> AppConfig:
+    """Load the configuration and resolve the effective allowed roots.
+
+    Precedence:
+
+    1. ``cli_roots`` (from ``--allow-root``) if given, otherwise the
+       default roots (home plus CWD).
+    2. ``allowed_roots`` from the config file, if present, intersected
+       with the CLI roots so the configuration can only restrict roots.
+    3. Defaults otherwise.
+    """
+    from fs_tool.core.filesystem import normalize_path
+    from fs_tool.safety.validation import default_allowed_roots
+
+    path = Path(config_path) if config_path is not None else _default_config_path()
+
+    data: dict[str, Any] = {}
+    if path.exists():
+        try:
+            with path.open("rb") as handle:
+                data = tomllib.load(handle)
+        except tomllib.TOMLDecodeError as exc:
+            raise ConfigError(f"Invalid TOML in {path}: {exc}") from exc
+        except OSError as exc:
+            raise ConfigError(f"Cannot read config file {path}: {exc.strerror or exc}") from exc
+
+    config_roots = _config_allowed_roots(data)
+
+    base: tuple[Path, ...]
+    if cli_roots:
+        base = cli_roots
+    else:
+        base = default_allowed_roots()
+    # Deduplicate (e.g. CWD == home) and normalize spellings.
+    base = tuple(dict.fromkeys(normalize_path(root) for root in base))
+
+    if config_roots is not None:
+        config_roots = tuple(dict.fromkeys(normalize_path(root) for root in config_roots))
+        # Intersection keeps CLI/default authorization: the configuration
+        # may only restrict roots, never expand them.
+        effective = tuple(root for root in base if root in config_roots)
+        return AppConfig(allowed_roots=effective)
+
+    return AppConfig(allowed_roots=base)

fs_tool/core/errors.py

@@ -0,0 +1,88 @@
+"""Centralized error handling for fs-tool.
+
+Stable error codes mapped to process exit codes (plan.md section 4.3).
+All application errors inherit from :class:`FsToolError` and carry an
+error code, a human-readable message, and optional context (path,
+details). Unexpected bugs are not swallowed silently: they propagate
+to the CLI boundary, which reports them as a generic failure.
+"""
+
+from __future__ import annotations
+
+from enum import Enum
+from typing import Any
+
+
+class ErrorCode(str, Enum):
+    """Stable machine-readable error codes.
+
+    The numeric process exit code is derived from the error code via
+    :data:`EXIT_CODES`.
+    """
+
+    # 1 - Operation failed or verification found discrepancies.
+    OPERATION_FAILED = "OPERATION_FAILED"
+    VERIFICATION_FAILED = "VERIFICATION_FAILED"
+
+    # 2 - Invalid arguments or incomplete analysis.
+    INVALID_ARGUMENT = "INVALID_ARGUMENT"
+    INCOMPLETE_ANALYSIS = "INCOMPLETE_ANALYSIS"
+
+    # 3 - Access denied or safety restriction.
+    ACCESS_DENIED = "ACCESS_DENIED"
+    ROOT_NOT_ALLOWED = "ROOT_NOT_ALLOWED"
+
+    # 4 - Operation conflict.
+    TARGET_EXISTS = "TARGET_EXISTS"
+    TYPE_CONFLICT = "TYPE_CONFLICT"
+
+    # 5 - Incomplete scan or verification (not fully verifiable).
+    INCOMPLETE_SCAN = "INCOMPLETE_SCAN"
+    INCOMPLETE_VERIFICATION = "INCOMPLETE_VERIFICATION"
+
+
+EXIT_CODES: dict[ErrorCode, int] = {
+    ErrorCode.OPERATION_FAILED: 1,
+    ErrorCode.VERIFICATION_FAILED: 1,
+    ErrorCode.INVALID_ARGUMENT: 2,
+    ErrorCode.INCOMPLETE_ANALYSIS: 2,
+    ErrorCode.ACCESS_DENIED: 3,
+    ErrorCode.ROOT_NOT_ALLOWED: 3,
+    ErrorCode.TARGET_EXISTS: 4,
+    ErrorCode.TYPE_CONFLICT: 4,
+    ErrorCode.INCOMPLETE_SCAN: 5,
+    ErrorCode.INCOMPLETE_VERIFICATION: 5,
+}
+
+
+class FsToolError(Exception):
+    """Base class for all fs-tool errors.
+
+    Attributes:
+        code: Stable error code.
+        message: Human-readable, actionable error message.
+        path: Filesystem path related to the error, if any.
+        details: Additional structured context.
+    """
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        code: ErrorCode = ErrorCode.OPERATION_FAILED,
+        path: str | None = None,
+        details: dict[str, Any] | None = None,
+    ) -> None:
+        super().__init__(message)
+        self.code = code
+        self.message = message
+        self.path = path
+        self.details = details or {}
+
+    @property
+    def exit_code(self) -> int:
+        """Process exit code for this error code."""
+        return EXIT_CODES[self.code]
+
+    def __str__(self) -> str:
+        return self.message

fs_tool/core/filesystem.py

@@ -0,0 +1,50 @@
+"""Filesystem path normalization (plan.md Phase 1).
+
+Pure lexical normalization: expand the user's home directory, make the
+path absolute and collapse ``.`` and ``..`` components. No filesystem
+access is performed and symlinks are not resolved here (see
+:func:`resolve_path` for symlink-aware resolution).
+"""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+
+def normalize_path(path: str | Path) -> Path:
+    """Lexically normalize ``path``.
+
+    Expands ``~``, makes the path absolute against the current working
+    directory and collapses redundant separators, ``.`` and up-level
+    references (``..``) without touching the filesystem. Symlinks are
+    not resolved; use :func:`resolve_path` for that.
+    """
+    expanded = os.path.expanduser(os.fspath(path))
+    absolute = os.path.abspath(expanded)
+    parsed = Path(absolute)
+    collapsed: list[str] = []
+    for part in parsed.parts:
+        if part == "." or part == "":
+            continue
+        if part == parsed.anchor:
+            if collapsed and collapsed[-1] == parsed.anchor:
+                continue
+            collapsed.append(part)
+            continue
+        if part == "..":
+            if len(collapsed) > 1 and collapsed[-1] != parsed.anchor:
+                collapsed.pop()
+            # At the filesystem root, ".." goes nowhere.
+            continue
+        collapsed.append(part)
+    return Path(*collapsed)
+
+
+def resolve_path(path: str | Path) -> Path:
+    """Resolve symlinks and up-level references as far as possible.
+
+    Unlike :func:`normalize_path`, this accesses the filesystem. Missing
+    path components are kept as-is (``strict=False`` behavior).
+    """
+    return Path(os.path.expanduser(os.fspath(path))).resolve(strict=False)

fs_tool/core/hashing.py

@@ -0,0 +1,49 @@
+"""SHA-256 hashing of files (plan.md Phase 1, P1-T09).
+
+Hashing is read-only: symlinks are never followed and only regular
+files are hashed. Special files (FIFOs, sockets, devices) are
+explicitly excluded and never opened.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import os
+import stat
+from pathlib import Path
+
+CHUNK_SIZE = 1 << 20  # 1 MiB
+
+
+def sha256_of_file(path: str | Path) -> str | None:
+    """Return the SHA-256 hex digest of ``path`` or ``None``.
+
+    ``None`` is returned when the path does not exist, is not a regular
+    file (symlinks, directories, FIFOs, sockets, devices), or its
+    contents cannot be read. Errors are not raised: callers report them
+    as traversal or inventory errors instead.
+    """
+    p = Path(path)
+    try:
+        st = p.lstat()
+    except OSError:
+        return None
+    if not stat.S_ISREG(st.st_mode):
+        return None
+
+    flags = os.O_RDONLY
+    if hasattr(os, "O_NOFOLLOW"):
+        flags |= os.O_NOFOLLOW  # never follow a symlink at open time
+    try:
+        fd = os.open(p, flags)
+    except OSError:
+        return None
+
+    digest = hashlib.sha256()
+    try:
+        with os.fdopen(fd, "rb") as f:
+            for chunk in iter(lambda: f.read(CHUNK_SIZE), b""):
+                digest.update(chunk)
+    except OSError:
+        return None
+    return digest.hexdigest()

fs_tool/core/models.py

@@ -0,0 +1,44 @@
+"""Internal filesystem data model.
+
+A consistent internal representation for filesystem entries
+(plan.md section 8). The model is independent of JSON serialization
+and terminal rendering. Fields that are unavailable or not applicable
+are ``None``.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import Enum
+from typing import Any
+
+
+class EntryType(str, Enum):
+    FILE = "file"
+    DIRECTORY = "directory"
+    SYMLINK = "symlink"
+    OTHER = "other"
+
+
+@dataclass(frozen=True)
+class FilesystemEntry:
+    """A single filesystem entry as observed by fs-tool."""
+
+    path: str
+    name: str
+    rel_path: str | None = None
+    type: EntryType = EntryType.FILE
+    extension: str | None = None
+    size: int | None = None
+    modified: str | None = None
+    created: str | None = None
+    accessed: str | None = None
+    changed: str | None = None
+    mode: str | None = None
+    owner: str | None = None
+    mime_type: str | None = None
+    is_symlink: bool = False
+    target: str | None = None
+    sha256: str | None = None
+    dev_ino: str | None = None
+    metadata: dict[str, Any] | None = None