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

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

@@ -0,0 +1,46 @@
+# Naming Conventions in Python Projects
+
+In Python projects, it's crucial to use consistent naming conventions to ensure code readability and maintainability. The choice between underscores (`_`) and hyphens (`-`) largely depends on the context.
+
+---
+
+## Underscores (`_`) – Snake_case
+
+Primarily use underscores **within your Python code** for multi-word names. This is known as `snake_case`.
+
+* **Python Package Names (Internal):** The importable name of your Python package (e.g., the folder under `src/`) should use underscores.
+    * **Example:** `src/my_python_package` is imported as `import my_python_package`.
+* **Module Names (.py files):** Python file names that are modules should also use underscores.
+    * **Example:** `my_module.py`, `data_processing.py`.
+* **Variables, Functions, and Methods:** Within your code, these names should follow `snake_case`.
+    * **Example:** `my_variable`, `calculate_total()`, `_private_function()`.
+
+---
+
+## Hyphens (`-`) – Kebab-case
+
+Primarily use hyphens **outside of your Python code** for filesystem, URL, and human-readable names. This is often referred to as `kebab-case`.
+
+* **PyPI Package Name (Project Name):** The name under which your project is published on PyPI and installed with `pip install` should use hyphens.
+    * **Example:** In `pyproject.toml`: `name = "my-python-project"`. Installation: `pip install my-python-project`.
+* **Main Project Folder / Repository Name:** The root folder of your project in the file system.
+    * **Example:** `my-python-project/`.
+* **Documentation Folders and Files (MkDocs, ReadTheDocs):** Folders and Markdown files within your documentation.
+    * **Example:** `docs/getting-started/installation-guide.md`.
+* **Command-Line Tools / Scripts:** Names for executable scripts you define in your `pyproject.toml` under `[project.scripts]`.
+    * **Example:** `my-cli-tool = "my_python_package.cli:main"`.
+
+---
+
+## Summary of Recommendations
+
+| Context                       | Recommended Convention | Example                          |
+| :---------------------------- | :--------------------- |:---------------------------------|
+| **Internal Python Name** | Underscores (`_`)      | `my_python_package`              |
+| **PyPI / Project Name** | Hyphens (`-`)          | `my-python-package`              |
+| **Module Filename** | Underscores (`_`)      | `my_module.py`                   |
+| **Repository/Root Folder** | Hyphens (`-`)          | `my-python-project/`             |
+| **Docs Folders/Files** | Hyphens (`-`)          | `getting-started/cli-usage.md`   |
+| **CLI Commands** | Hyphens (`-`)          | `my-cli-tool`                    |
+
+Consistently applying these rules significantly improves the clarity and professionalism of your Python project.

fs_tool_cli-0.1.2.data/data/share/fs-tool/docs/funding/funding.md

@@ -0,0 +1,55 @@
+# 🧡 FUNDING
+
+Hey there! If you find this project helpful and would like to support its continued development, here are a few ways you can contribute:
+
+-----
+
+## Why Support?
+
+Your support helps me dedicate more time and resources to maintaining and improving this project. It allows for:
+
+  * **Bug fixes and ongoing maintenance:** Ensuring the project remains stable and up-to-date.
+  * **New features and enhancements:** Adding exciting new functionalities to make the project even better.
+  * **Documentation and support:** Providing clear guides and assistance to users.
+
+-----
+
+## How You Can Contribute
+
+Here are the ways you can show your support:
+
+### 1\. GitHub Sponsors
+
+The easiest and most direct way to support this project is through **GitHub Sponsors**. You can set up a recurring donation or make a one-time contribution.
+
+[**Become a Sponsor on GitHub**](https://github.com/sponsors/pamagister)
+
+
+### 2\. Paypal
+
+If you prefer a simpler, one-time contribution, you can PayPal me! It's a great way to show appreciation.
+
+[**Support via PayPal**](https://www.paypal.me/PaulDD)
+
+
+### 3\. Cryptocurrency
+
+If you're into crypto, you can send a donation to the following addresses:
+
+  * **Bitcoin (BTC):** bc1q070wj0t29gpnf59rq77uz39ruq5ahg9vhakzpq
+
+  * **Lightning (ETH):** *coming soon*
+
+### 4\. Spread the Word\!
+
+Even if you can't contribute financially, you can still help immensely by:
+
+  * **Starring the repository:** This helps increase visibility.
+  * **Sharing the project:** Let others know about it on social media or in your network.
+  * **Contributing code:** Open issues, submit pull requests, or help with documentation.
+
+-----
+
+## Thank You\!
+
+Every bit of support, no matter how small, is greatly appreciated and helps keep this project going. Thank you for being a part of this journey\!

fs_tool_cli-0.1.2.data/data/share/fs-tool/docs/getting-started/install.md

@@ -0,0 +1,45 @@
+# Installation
+
+
+## 🐍 PyPI
+
+Install the CLI from [PyPI](https://pypi.org/):
+
+```bash
+pip install fs-tool
+```
+
+The package includes the `docs/` documentation and `res/` sample files under
+`share/fs-tool/` in the active Python environment's data directory.
+
+### Run the CLI
+
+```bash
+fs-tool [OPTIONS] path/to/file
+```
+
+## 👩🏼‍💻 Run from source
+
+### Clone the repository
+
+```bash
+git clone
+```
+
+### Navigate to the project directory
+
+```bash
+cd fs-tool
+```
+
+### Install dependencies
+
+```bash
+uv sync --all-groups
+```
+
+### Run the CLI from source
+
+```bash
+uv run fs-tool [OPTIONS] path/to/file
+```

fs_tool_cli-0.1.2.data/data/share/fs-tool/docs/getting-started/virtual-environment.md

@@ -0,0 +1,29 @@
+# Setup virtual environment
+
+## Create `venv`
+
+Creating virtual environment `venv` using [uv](https://docs.astral.sh/uv/):
+```bash
+uv venv
+```
+
+## Activate `venv`
+
+Activating a Python virtual environment `venv`
+> Note: Replace `.venv` with your Venv folder name if you have chosen a different one.
+
+🔹 Windows (PowerShell)
+
+```bash
+.venv\Scripts\activate.ps1
+```
+
+🔹 Windows (CMD)
+```cmd
+.venv\Scripts\activate.bat
+```
+
+🔹 Linux / macOS (Bash/Zsh)
+```bash
+source .venv/bin/activate
+```

fs_tool_cli-0.1.2.data/data/share/fs-tool/docs/index.md

@@ -0,0 +1,77 @@
+# Welcome to fs-tool
+
+fs-tool is a lightweight, secure and agent-friendly command-line application for analyzing, 
+organizing and restructuring local filesystems. 
+Its primary purpose is to provide an interface for inspecting directory structures, 
+understanding file contents and metadata, identifying duplicates, comparing directory trees, 
+and performing file operations.
+
+[![Github CI Status](https://github.com/pamagister/fs-tool/actions/workflows/main.yml/badge.svg)](https://github.com/pamagister/fs-tool/actions)
+[![GitHub release](https://img.shields.io/github/v/release/pamagister/fs-tool)](https://github.com/pamagister/fs-tool/releases)
+[![Read the Docs](https://readthedocs.org/projects/fs-tool/badge/?version=stable)](https://fs-tool.readthedocs.io/en/stable/)
+[![License](https://img.shields.io/github/license/pamagister/fs-tool)](https://github.com/pamagister/fs-tool/blob/main/LICENSE)
+[![GitHub issues](https://img.shields.io/github/issues/pamagister/fs-tool)](https://github.com/pamagister/fs-tool/issues)
+[![PyPI](https://img.shields.io/pypi/v/fs-tool)](https://pypi.org/project/fs-tool-cli/)
+[![Downloads](https://pepy.tech/badge/fs-tool)](https://pepy.tech/project/fs-tool-cli/)
+
+
+## Project Vision
+
+`fs-tool` is a lightweight, secure and agent-friendly command-line application for analyzing, organizing and restructuring local filesystems.
+
+Its primary purpose is to provide a reliable interface for inspecting directory structures, understanding file contents and metadata, identifying duplicates, comparing directory trees, and performing controlled file operations.
+
+The tool should be useful both for interactive human users and for automated workflows.
+
+## Guiding Principle
+
+**The agent makes decisions; fs-tool provides the information and executes filesystem operations safely and deterministically.**
+
+The application must remain independent of any particular AI agent, MCP implementation or external automation framework.
+
+## Design Philosophy
+
+- Prefer simplicity over unnecessary abstraction.
+- Keep the Python filesystem core independent of the CLI.
+- Use structured JSON output as the primary interface.
+- Provide readable human-oriented output as an alternative.
+- Make filesystem operations predictable, transparent and verifiable.
+- Never silently overwrite or delete user data.
+- Require explicit authorization for potentially risky operations.
+- Favor deterministic results and reproducible inventories.
+- Keep dependencies minimal.
+
+## Future Agentic Workflow
+
+The long-term vision is to enable AI agents, especially OpenCode, to organize complex directory structures autonomously under controlled conditions.
+
+A typical workflow:
+
+1. Inspect and inventory the existing filesystem.
+2. Analyze filenames, metadata, file types and contents where appropriate.
+3. Identify duplicates, inconsistencies and organizational opportunities.
+4. Propose a target directory structure.
+5. Generate a concrete restructuring plan.
+6. Validate the plan and identify potential conflicts.
+7. Execute approved operations using fs-tool.
+8. Verify the resulting filesystem against the original inventory and intended changes.
+
+The agent is responsible for reasoning, planning and deciding what should happen. The CLI is responsible for executing individual operations safely and reporting their results.
+
+## Development Rules
+
+- Python >=3.11, managed with `uv`.
+- Use Typer for the CLI.
+- Use type hints and clear module boundaries.
+- Prefer Python standard-library functionality where practical.
+- Follow PEP 8 and use four spaces for indentation.
+- Keep line length at approximately 100 characters.
+- Write tests for filesystem operations and safety-critical behavior.
+- Document CLI commands and their JSON output schemas.
+- Do not introduce MCP-specific dependencies into the core application.
+
+## Scope
+
+The initial implementation focuses exclusively on the filesystem CLI.
+
+Agent orchestration, autonomous planning, MCP adapters and advanced LLM integrations are future extensions and must not unnecessarily influence the initial architecture.

fs_tool_cli-0.1.2.data/data/share/fs-tool/docs/usage/cli.md

@@ -0,0 +1,13 @@
+# Command Line Interface
+
+Command line options for fs_tool
+
+```bash
+fs-tool [OPTIONS] <input>
+```
+
+For development from a source checkout, the equivalent module invocation is:
+
+```bash
+python -m fs_tool [OPTIONS] <input>
+```