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

fs_tool/core/traversal.py

@@ -0,0 +1,225 @@
+"""Recursive directory traversal (plan.md Phase 1).
+
+Traversal is read-only: symlinks are recorded but never followed by
+default, special files are reported as unsupported and never opened,
+inaccessible entries are collected as errors instead of aborting the
+scan, and results are deterministically sorted by entry name.
+"""
+
+from __future__ import annotations
+
+import fnmatch
+import mimetypes
+import os
+import stat
+import sys
+from dataclasses import dataclass, field
+from datetime import UTC, datetime
+from pathlib import Path
+from typing import Literal
+
+from fs_tool.core.errors import ErrorCode, FsToolError
+from fs_tool.core.filesystem import normalize_path
+from fs_tool.core.models import EntryType, FilesystemEntry
+
+DEFAULT_IGNORE_DIRS: frozenset[str] = frozenset(
+    {
+        ".git",
+        ".venv",
+        "__pycache__",
+        ".pytest_cache",
+        ".ruff_cache",
+        ".mypy_cache",
+        "node_modules",
+        "build",
+        "dist",
+        ".idea",
+        ".vscode",
+    }
+)
+
+SortBy = Literal["name"]
+
+
+@dataclass(frozen=True)
+class TraversalError:
+    """An entry that could not be traversed or read."""
+
+    path: str
+    message: str
+
+
+@dataclass
+class TraversalResult:
+    """Result of a directory traversal."""
+
+    entries: list[FilesystemEntry] = field(default_factory=list)
+    errors: list[TraversalError] = field(default_factory=list)
+    complete: bool = True
+    skipped: int = 0
+
+
+def _iso_timestamp(seconds: float) -> str:
+    return datetime.fromtimestamp(seconds, tz=UTC).isoformat()
+
+
+def _entry_type(stat_result: os.stat_result | None, is_symlink: bool) -> EntryType:
+    if is_symlink:
+        return EntryType.SYMLINK
+    if stat_result is not None and stat.S_ISDIR(stat_result.st_mode):
+        return EntryType.DIRECTORY
+    if stat_result is not None and stat.S_ISREG(stat_result.st_mode):
+        return EntryType.FILE
+    return EntryType.OTHER
+
+
+def _build_entry(path: Path, root: Path, follow_symlinks: bool = False) -> FilesystemEntry:
+    """Build a :class:`FilesystemEntry` without following symlinks."""
+    try:
+        lst = path.lstat()
+    except OSError as exc:
+        raise FsToolError(
+            f"Cannot stat {path}: {exc.strerror or exc}",
+            code=ErrorCode.INVALID_ARGUMENT,
+            path=str(path),
+        ) from exc
+
+    is_symlink = stat.S_ISLNK(lst.st_mode)
+    target: str | None = None
+    if is_symlink and not follow_symlinks:
+        try:
+            target = os.readlink(path)
+        except OSError:
+            target = None
+
+    stat_result: os.stat_result | None = None
+    if not is_symlink or follow_symlinks:
+        try:
+            stat_result = path.stat()
+        except OSError:
+            stat_result = None
+
+    owner: str | None = None
+    if sys.platform != "win32":
+        from pwd import getpwuid  # POSIX only; Windows has no pwd module
+
+        try:
+            owner = getpwuid(lst.st_uid).pw_name
+        except KeyError:  # pragma: no cover - POSIX without uid entry
+            owner = None
+
+    created: str | None = None
+    birthtime = getattr(lst, "st_birthtime", None)
+    if birthtime is not None:
+        created = _iso_timestamp(birthtime)
+
+    return FilesystemEntry(
+        path=str(path),
+        name=path.name,
+        rel_path=str(path.relative_to(root)),
+        type=_entry_type(stat_result, is_symlink),
+        extension=path.suffix.lower() if path.suffix else None,
+        size=lst.st_size,
+        modified=_iso_timestamp(lst.st_mtime),
+        accessed=_iso_timestamp(lst.st_atime),
+        changed=_iso_timestamp(lst.st_ctime),
+        created=created,
+        mode=stat.filemode(lst.st_mode),
+        mime_type=mimetypes.guess_type(path)[0],
+        owner=owner,
+        is_symlink=is_symlink,
+        target=target,
+        dev_ino=f"{lst.st_dev}:{lst.st_ino}",
+    )
+
+
+def traverse(
+    root: str | Path,
+    *,
+    max_depth: int | None = None,
+    max_entries: int | None = None,
+    dirs_only: bool = False,
+    ignore_dirs: frozenset[str] | None = None,
+    ignore_patterns: tuple[str, ...] = (),
+    follow_symlinks: bool = False,
+    sort_by: SortBy = "name",
+) -> TraversalResult:
+    """Recursively traverse ``root`` and return its entries.
+
+    Symlinks are recorded but never followed unless ``follow_symlinks``
+    is set (cycles are still avoided). Inaccessible entries are
+    reported as errors and do not abort the scan. Entries are sorted
+    alphabetically by name within each directory.
+    """
+    if sort_by != "name":
+        raise FsToolError(
+            f"Unsupported sort_by value {sort_by!r}; only 'name' is supported",
+            code=ErrorCode.INVALID_ARGUMENT,
+        )
+
+    root_path = normalize_path(root)
+    ignored = set(DEFAULT_IGNORE_DIRS)
+    if ignore_dirs is not None:
+        ignored |= set(ignore_dirs)
+
+    result = TraversalResult()
+    visited_dirs: set[tuple[int, int]] = set()
+
+    def record_error(path: Path, message: str) -> None:
+        result.errors.append(TraversalError(path=str(path), message=message))
+        result.complete = False
+
+    def walk(directory: Path, depth: int) -> None:
+        """Walk ``directory``; ``depth`` is the level of its entries
+        relative to ``root`` (root's direct entries have depth 1)."""
+        if max_entries is not None and len(result.entries) >= max_entries:
+            result.complete = False
+            return
+        try:
+            pending = sorted(os.scandir(directory), key=lambda entry: entry.name)
+        except OSError as exc:
+            record_error(directory, f"Cannot read directory: {exc.strerror or exc}")
+            return
+        for entry in pending:
+            if max_entries is not None and len(result.entries) >= max_entries:
+                result.complete = False
+                return
+            name = entry.name
+            if name in ignored or any(fnmatch.fnmatch(name, p) for p in ignore_patterns):
+                result.skipped += 1
+                continue
+            path = Path(entry.path)
+            try:
+                is_link = entry.is_symlink()
+                is_dir = entry.is_dir(follow_symlinks=follow_symlinks)
+            except OSError as exc:
+                record_error(path, f"Cannot inspect entry: {exc.strerror or exc}")
+                continue
+            if is_link and not follow_symlinks:
+                if not dirs_only:
+                    _append_entry(path)
+                continue
+            if is_link and follow_symlinks:
+                try:
+                    real = entry.stat(follow_symlinks=True)
+                except OSError as exc:
+                    record_error(path, f"Cannot follow symbolic link: {exc.strerror or exc}")
+                    continue
+                key = (real.st_dev, real.st_ino)
+                if key in visited_dirs:
+                    result.skipped += 1
+                    continue
+                visited_dirs.add(key)
+            if not dirs_only or is_dir:
+                _append_entry(path)
+            if is_dir and (max_depth is None or depth < max_depth):
+                walk(path, depth + 1)
+
+    def _append_entry(path: Path) -> None:
+        try:
+            result.entries.append(_build_entry(path, root_path, follow_symlinks=follow_symlinks))
+        except FsToolError as exc:
+            record_error(path, exc.message)
+
+    walk(root_path, 1)
+    return result

fs_tool/output/__init__.py

@@ -0,0 +1 @@
+"""Output rendering: JSON envelope and plain-text presentation."""

fs_tool/output/json.py

@@ -0,0 +1,142 @@
+"""Common JSON response envelope.
+
+Every command returns the envelope structure described in plan.md
+section 4.3:
+
+.. code-block:: json
+
+   {
+     "schema_version": 1,
+     "success": true,
+     "command": "inspect.info",
+     "result": {},
+     "errors": [],
+     "warnings": [],
+     "complete": true
+   }
+
+``--help`` and ``--version`` are documented exceptions to the JSON
+envelope.
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import asdict, dataclass, field
+from typing import Any
+
+SCHEMA_VERSION = 1
+
+ENVELOPE_KEY_ORDER = (
+    "schema_version",
+    "success",
+    "command",
+    "result",
+    "errors",
+    "warnings",
+    "complete",
+)
+
+
+@dataclass(frozen=True)
+class Error:
+    """A structured error entry in the JSON envelope."""
+
+    code: str
+    message: str
+    path: str | None = None
+    details: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass(frozen=True)
+class Warning:
+    """A structured warning entry in the JSON envelope."""
+
+    code: str
+    message: str
+    path: str | None = None
+    details: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass(frozen=True)
+class Envelope:
+    """The common JSON response envelope."""
+
+    schema_version: int = SCHEMA_VERSION
+    success: bool = True
+    command: str = ""
+    result: Any = None
+    errors: tuple[Error, ...] = ()
+    warnings: tuple[Warning, ...] = ()
+    complete: bool = True
+
+    def to_dict(self) -> dict[str, Any]:
+        """Serialize to a plain dict with stable key order."""
+        ordered: dict[str, Any] = {}
+        ordered["schema_version"] = self.schema_version
+        ordered["success"] = self.success
+        ordered["command"] = self.command
+        ordered["result"] = self.result
+        ordered["errors"] = [asdict(error) for error in self.errors]
+        ordered["warnings"] = [asdict(warning) for warning in self.warnings]
+        ordered["complete"] = self.complete
+        return ordered
+
+    def to_json(self, **kwargs: Any) -> str:
+        """Serialize to deterministic JSON."""
+        return json.dumps(self.to_dict(), **kwargs)
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> Envelope:
+        return cls(
+            schema_version=int(data.get("schema_version", SCHEMA_VERSION)),
+            success=bool(data.get("success", True)),
+            command=str(data.get("command", "")),
+            result=data.get("result"),
+            errors=tuple(Error(**item) for item in data.get("errors", [])),
+            warnings=tuple(Warning(**item) for item in data.get("warnings", [])),
+            complete=bool(data.get("complete", True)),
+        )
+
+    @classmethod
+    def from_json(cls, text: str) -> Envelope:
+        return cls.from_dict(json.loads(text))
+
+
+def success_result(
+    command: str,
+    result: Any = None,
+    *,
+    complete: bool = True,
+    warnings: tuple[Warning, ...] = (),
+) -> Envelope:
+    """Build a successful envelope."""
+    return Envelope(
+        schema_version=SCHEMA_VERSION,
+        success=True,
+        command=command,
+        result=result,
+        errors=(),
+        warnings=warnings,
+        complete=complete,
+    )
+
+
+def failure_result(
+    command: str,
+    errors: tuple[Error, ...],
+    *,
+    complete: bool = False,
+    result: Any = None,
+    warnings: tuple[Warning, ...] = (),
+) -> Envelope:
+    """Build a failed envelope."""
+    return Envelope(
+        schema_version=SCHEMA_VERSION,
+        success=False,
+        command=command,
+        result=result,
+        errors=errors,
+        warnings=warnings,
+        complete=complete,
+    )

fs_tool/output/plain.py

@@ -0,0 +1,58 @@
+"""Plain-text presentation (plan.md section 10.2).
+
+Terminal output is optional and never influences filesystem operations.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from fs_tool.core.models import EntryType, FilesystemEntry
+
+
+def render_tree(entries: list[FilesystemEntry], root: Path) -> str:
+    """Render traversal entries as a plain-text tree rooted at ``root``.
+
+    Entries must be ordered as produced by the traversal (pre-order,
+    siblings sorted by name).
+    """
+
+    def parts_of(entry: FilesystemEntry) -> tuple[str, ...]:
+        assert entry.rel_path is not None
+        return Path(entry.rel_path).parts
+
+    def parent_of(entry: FilesystemEntry) -> tuple[str, ...]:
+        return parts_of(entry)[:-1]
+
+    def depth_of(entry: FilesystemEntry) -> int:
+        return len(parts_of(entry))
+
+    def is_last(index: int) -> bool:
+        entry = entries[index]
+        parent = parent_of(entry)
+        depth = depth_of(entry)
+        for later in entries[index + 1 :]:
+            later_parts = parts_of(later)
+            if len(later_parts) == depth and later_parts[:-1] == parent:
+                return False  # a sibling follows
+            if len(later_parts) <= len(parent):
+                return True  # moved past this entry's subtree
+        return True
+
+    root_name = root.name or str(root)
+    lines = [f"{root_name}/"]
+    stack: list[bool] = []  # is_last flag of each ancestor level
+
+    for index, entry in enumerate(entries):
+        depth = depth_of(entry)
+        while len(stack) > depth - 1:
+            stack.pop()
+        prefix = "".join("    " if was_last else "│   " for was_last in stack)
+        connector = "└── " if is_last(index) else "├── "
+        marker = "/" if entry.type == EntryType.DIRECTORY else ""
+        if entry.is_symlink and entry.target:
+            marker += f" -> {entry.target}"
+        lines.append(f"{prefix}{connector}{entry.name}{marker}")
+        stack.append(is_last(index))
+
+    return "\n".join(lines)

fs_tool/safety/__init__.py

@@ -0,0 +1 @@
+"""Filesystem safety: allowed-root checks and path traversal protection."""

fs_tool/safety/validation.py

@@ -0,0 +1,81 @@
+"""Allowed-root validation (plan.md Phase 1, decision D6).
+
+By default only the user's home directory and the current working
+directory are accessible. Anything else requires explicit authorization
+via ``--allow-root``. The current working directory of ``/`` is not
+implicitly allowed.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from fs_tool.core.errors import ErrorCode, FsToolError
+from fs_tool.core.filesystem import normalize_path, resolve_path
+
+
+class PathNotAllowedError(FsToolError):
+    """A requested path lies outside the allowed roots."""
+
+    def __init__(self, path: str | Path, roots: tuple[Path, ...]) -> None:
+        super().__init__(
+            f"Path not allowed: {path}",
+            code=ErrorCode.ROOT_NOT_ALLOWED,
+            path=str(path),
+            details={"roots": [str(root) for root in roots]},
+        )
+
+
+def default_allowed_roots() -> tuple[Path, ...]:
+    """Default allowed roots: home plus CWD, unless CWD is ``/`` (D6)."""
+    roots = [Path.home()]
+    if Path.cwd() != Path("/"):
+        roots.append(Path.cwd())
+    return tuple(roots)
+
+
+def is_within_root(path: Path, root: Path) -> bool:
+    """True if ``path`` is located at or below ``root`` (lexical check)."""
+    try:
+        path.relative_to(root)
+    except ValueError:
+        return False
+    return True
+
+
+def validate_path(
+    path: str | Path,
+    allowed_roots: tuple[Path, ...] | None = None,
+) -> Path:
+    """Return the normalized path if it is within an allowed root.
+
+    Both the lexically normalized path and the symlink-resolved path
+    must lie within an allowed root, so symlinks cannot be used to
+    escape an allowed root. Raises :class:`PathNotAllowedError`
+    (exit code 3) otherwise.
+    """
+    roots = tuple(allowed_roots) if allowed_roots is not None else default_allowed_roots()
+    candidates = (normalize_path(path), resolve_path(path))
+    for candidate in candidates:
+        if not any(is_within_root(candidate, root) for root in roots):
+            raise PathNotAllowedError(path, roots)
+    return candidates[0]
+
+
+def symlink_components(path: str | Path) -> list[Path]:
+    """Return the components of ``path`` that are symbolic links.
+
+    Uses ``lstat`` so symlinks are never followed. Components are
+    returned from the filesystem root toward ``path``.
+    """
+    resolved = normalize_path(path)
+    links: list[Path] = []
+    current: Path = resolved
+    while True:
+        if current.is_symlink():
+            links.append(current)
+        if current == current.parent:
+            break
+        current = current.parent
+    links.reverse()
+    return links

fs_tool_cli-0.1.2.data/data/share/fs-tool/docs/.nav.yml

@@ -0,0 +1,15 @@
+# Navigation tree powered by mkdocs-awesome-nav
+#
+# This MkDocs plugin gives you full control over your navigation structure
+# without having to write the entire thing by hand. Whether you just want
+# to add an external link or restructure the entire navigation tree,
+# awesome-nav has you covered.
+#
+# https://github.com/lukasgeiter/mkdocs-awesome-nav
+
+nav:
+  - index.md
+  - develop
+  - getting-started
+  - usage
+  - funding

fs_tool_cli-0.1.2.data/data/share/fs-tool/docs/css/custom.css

@@ -0,0 +1,5 @@
+/* docs/_static/custom.css */
+.wy-nav-content {
+    max-width: 1000px;
+    margin: 0 auto;
+}

fs_tool_cli-0.1.2.data/data/share/fs-tool/docs/develop/contributing.md

@@ -0,0 +1,142 @@
+# How to develop on this project
+
+fs-tool welcomes contributions from the community.
+
+These instructions are basically for linux base systems. (Linux, MacOS, BSD, etc.)
+
+
+## Setting up your own fork of this repo.
+
+- On github interface click on `Fork` button.
+- Clone your fork of this repo. `git clone git@github.com:YOUR_GIT_USERNAME/fs-tool.git`
+- Enter the directory `cd fs-tool`
+- Add upstream repo `git remote add upstream https://github.com/pamagister/fs-tool`
+
+## Setting up your own virtual environment
+
+Run `make virtualenv` to create a virtual environment.
+then activate it with `source .venv/bin/activate`.
+
+## Install the project in develop mode
+
+Run `make install` to install the project in develop mode.
+
+## Run the tests to ensure everything is working
+
+Run `make test` to run the tests.
+
+## Create a new branch to work on your contribution
+
+Run `git checkout -b my_contribution`
+
+## Make your changes
+
+Edit the files using your preferred editor. (we recommend PyCharm)
+
+## Format the code
+
+Run `make fmt` to format the code.
+
+## Run the linter
+
+Run `make lint` to run the linter.
+
+## Test your changes
+
+Run `make test` to run the tests.
+
+Review the coverage report and add tests for relevant uncovered behavior.
+
+## Build the docs locally
+
+Run `make docs` to build the docs.
+
+Ensure your new changes are documented.
+
+## Commit your changes
+
+This project uses [conventional git commit messages](https://www.conventionalcommits.org/en/v1.0.0/).
+
+Example: `fix(package): update setup.py arguments 🎉` (emojis are fine too)
+
+## Push your changes to your fork
+
+Run `git push origin my_contribution`
+
+## Submit a pull request
+
+On github interface, click on `Pull Request` button.
+
+Wait CI to run and one of the developers will review your PR.
+## Makefile utilities
+
+This project comes with a `Makefile` that contains a number of useful utility.
+
+```bash 
+❯ make
+Usage: make <target>
+Targets:
+help:             ## Show the help.
+install:          ## Install the project and all dependency groups.
+fmt:              ## Format source code and tests.
+lint:             ## Run lint, formatting, and type checks.
+test:             ## Run tests and generate coverage report.
+check:            ## Run formatting, lint, and the test suite.
+build:            ## Build the Python sdist and wheel, including docs/ and res/.
+release:          ## Check, create, and push a version tag to trigger GitHub release workflows.
+docs:             ## Build and sync the documentation.
+```
+
+## Making a new release
+
+This project uses [semantic versioning](https://semver.org/) and tags releases with `X.Y.Z`.
+The package version is derived from the Git tag. Running `make release` locally runs the checks,
+suggests the next patch version, creates the tag, and pushes it. GitHub Actions then builds the
+Python distributions, creates the GitHub release, and publishes to PyPI.
+
+PyPI publishing requires a repository secret named `PYPI_API_TOKEN`, generated on
+[pypi.org](https://pypi.org/account/).
+
+To trigger a new release all you need to do is.
+
+1. Commit all intended changes and ensure the worktree is clean.
+2. Verify your Git author identity with `git config user.name` and `git config user.email`.
+3. Run `make release` and confirm or edit the suggested version when prompted.
+
+`make release` does not modify or commit project files. It refuses to release with uncommitted
+changes or an invalid/already existing version tag.
+
+### Troubleshooting
+
+#### 🧩 Git Push Authentication Error
+
+If you encounter the following error during `make release` or when pushing manually:
+
+```bash
+remote: Invalid username or token. Password authentication is not supported for Git operations.
+fatal: Authentication failed for '[https://github.com/](https://github.com/)<user>/<repo>.git/'
+```
+
+GitHub no longer supports password-based authentication over HTTPS.  
+To fix this, you need to use a **Personal Access Token (PAT)** instead of your password.
+
+**Steps to resolve:**
+
+1. Go to [GitHub → Settings → Developer settings → Personal access tokens → Tokens (classic)](https://github.com/settings/tokens).
+2. Click **Generate new token (classic)** and select the following scopes:
+   - `repo`
+   - `workflow` (optional, for triggering GitHub Actions)
+3. Copy the generated token — you’ll only see it once.
+4. Update your Git remote to include your GitHub username:
+   ```bash
+   git remote set-url origin https://<YOUR_GITHUB_USERNAME>@github.com/<YOUR_GITHUB_USERNAME>/<YOUR_REPOSITORY>.git
+   ```
+
+5. The next time you push, Git will prompt for your password — **paste the token** instead.
+6. (Optional) To store credentials for future pushes:
+
+   ```bash
+   git config --global credential.helper store
+   ```
+
+After this setup, `make release` and manual pushes will work without further authentication errors.