fs-tool-cli 0.1.2__tar.gz

fs_tool_cli-0.1.2/.agents/skills/filesystem-organizer/SKILL.md

@@ -0,0 +1,65 @@
+# Filesystem Organization Skill
+
+DRAFT! DO NOT USE YET!
+
+## Purpose
+
+Use `fs-tool` to analyze, plan and safely reorganize local filesystems.
+
+The agent is responsible for understanding the data and making organizational decisions. `fs-tool` is responsible for executing controlled filesystem operations.
+
+## General Workflow
+
+### 1. Understand
+
+- Identify the target directory and accessible filesystem roots.
+- Inspect the existing directory structure.
+- Generate an inventory where appropriate.
+- Examine file metadata, types, sizes and timestamps.
+- Inspect file contents selectively when necessary.
+- Identify duplicates, inconsistencies and poorly named files.
+
+### 2. Analyze
+
+- Understand the apparent purpose and relationships of files.
+- Identify logical groups and organizational opportunities.
+- Distinguish confirmed information from assumptions.
+- Avoid moving files based on filenames alone when relevant metadata is available.
+
+### 3. Plan
+
+- Propose a consistent target directory structure.
+- Map existing files and directories to their intended destinations.
+- Identify renaming requirements and potential conflicts.
+- Preserve existing information and avoid unnecessary changes.
+- Present the proposed changes before execution.
+
+### 4. Validate
+
+- Check all source and destination paths.
+- Identify naming conflicts and duplicate content.
+- Verify that the proposed operations are supported.
+- Generate and inspect a dry-run before execution.
+
+### 5. Execute
+
+- Use `fs-tool` for filesystem modifications.
+- Obtain the required authorization for write and rename operations.
+- Never overwrite or delete data without explicit authorization.
+- Execute operations in manageable batches.
+- Record relevant operation results.
+
+### 6. Verify
+
+- Compare the resulting filesystem with the intended target structure.
+- Verify copied or moved files using hashes where appropriate.
+- Identify missing, unexpected or changed files.
+- Report incomplete operations and unresolved conflicts.
+
+## Guiding Principles
+
+- Preserve data integrity above all else.
+- Prefer understandable structures over unnecessary complexity.
+- Never guess when information can be inspected.
+- Keep the user informed about significant decisions.
+- Make all modifications traceable and verifiable.

fs_tool_cli-0.1.2/.github/FUNDING.yml

@@ -0,0 +1,12 @@
+# These are supported funding model platforms
+
+github: [pamagister]
+patreon: # Replace with a single Patreon username
+open_collective: # Replace with a single Open Collective username
+ko_fi: # Replace with a single Ko-fi username
+tidelift: # Replace with a single Tidelift platform-name/package-name e.g., npm/babel
+community_bridge: # Replace with a single Community Bridge project-name e.g., cloud-foundry
+liberapay: # Replace with a single Liberapay username
+issuehunt: # Replace with a single IssueHunt username
+otechie: # Replace with a single Otechie username
+custom: ["https://www.paypal.me/PaulDD"]

fs_tool_cli-0.1.2/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,31 @@
+---
+name: Bug report
+about: Create a report to help us improve
+title: ''
+labels: bug, help wanted
+assignees: ''
+
+---
+
+**Describe the bug**
+A clear and concise description of what the bug is.
+
+**To Reproduce**
+Steps to reproduce the behavior:
+1. Go to '...'
+2. Click on '....'
+3. Scroll down to '....'
+4. See error
+
+**Expected behavior**
+A clear and concise description of what you expected to happen.
+
+**Screenshots**
+If applicable, add screenshots to help explain your problem.
+
+**Desktop (please complete the following information):**
+ - OS: [e.g. iOS]
+ - Version [e.g. 22]
+
+**Additional context**
+Add any other context about the problem here.

fs_tool_cli-0.1.2/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,20 @@
+---
+name: Feature request
+about: Suggest an idea for this project
+title: ''
+labels: enhancement, question
+assignees: ''
+
+---
+
+**Is your feature request related to a problem? Please describe.**
+A clear and concise description of what the problem is. Ex. I'm always frustrated when [...]
+
+**Describe the solution you'd like**
+A clear and concise description of what you want to happen.
+
+**Describe alternatives you've considered**
+A clear and concise description of any alternative solutions or features you've considered.
+
+**Additional context**
+Add any other context or screenshots about the feature request here.

fs_tool_cli-0.1.2/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,15 @@
+### Summary :memo:
+_Write an overview about it._
+
+### Details
+_Describe more what you did on changes._
+1. (...)
+2. (...)
+
+### Bugfixes :bug: (delete if dind't have any)
+-
+
+### Checks
+- [ ] Closed #798
+- [ ] Tested Changes
+- [ ] Stakeholder Approval

fs_tool_cli-0.1.2/.github/actions/setup-environment/action.yml

@@ -0,0 +1,15 @@
+name: Setup Environment
+
+description: Setup uv environment
+
+runs:
+  using: "composite"
+  steps:
+    - name: Install uv
+      uses: astral-sh/setup-uv@v3
+      with:
+        version: "latest"
+
+    - name: Sync dependencies
+      run: uv sync --all-groups
+      shell: bash

fs_tool_cli-0.1.2/.github/dependabot.yml

@@ -0,0 +1,6 @@
+version: 2
+updates:
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"

fs_tool_cli-0.1.2/.github/workflows/main.yml

@@ -0,0 +1,53 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+  workflow_dispatch:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+
+jobs:
+  test:
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.11"]
+        os: [ubuntu-latest, macos-latest, windows-latest]
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-python@v6
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Setup environment
+        uses: ./.github/actions/setup-environment
+      - name: Run checks
+        if: runner.os != 'Windows'
+        run: make check
+      - name: Run Windows checks
+        if: runner.os == 'Windows'
+        shell: bash
+        run: |
+          uv run ruff check src/ tests/
+          uv run ruff format --check src/ tests/
+          uv run mypy src/
+          uv run pytest -v --cov=fs_tool -l --tb=short --maxfail=1 tests/
+          uv run coverage xml
+
+  build:
+    needs: test
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.11"
+      - name: Setup environment
+        uses: ./.github/actions/setup-environment
+      - name: Build Python distributions
+        run: make build

fs_tool_cli-0.1.2/.github/workflows/release.yml

@@ -0,0 +1,48 @@
+name: Upload Python Package
+permissions:
+  contents: write
+
+on:
+  push:
+    tags:
+      - "*"
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: false
+
+jobs:
+  release:
+    name: Create Release
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          fetch-depth: 0
+      - name: Release
+        uses: softprops/action-gh-release@v2
+        with:
+          generate_release_notes: true
+
+  deploy:
+    needs: release
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      id-token: write
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          fetch-depth: 0
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.11"
+      - name: Install build tools
+        run: python -m pip install --upgrade build
+      - name: Build distributions
+        run: python -m build
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

fs_tool_cli-0.1.2/.github/workflows/update_readme.yml

@@ -0,0 +1,38 @@
+name: Sync README with docs/index.md
+
+permissions:
+  contents: write
+
+on:
+  push:
+    paths:
+      - "docs/index.md"
+    branches: [main]
+  workflow_dispatch:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: false
+
+jobs:
+  sync:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - name: Set up Python
+        uses: actions/setup-python@v7
+        with:
+          python-version: "3.11"
+      - name: Update README.md
+        run: python scripts/update_readme.py
+      - name: Commit changes
+        run: |
+          git config user.name "github-actions"
+          git config user.email "github-actions@github.com"
+          git add README.md
+          if git diff --cached --quiet; then
+            echo "README.md is already in sync."
+            exit 0
+          fi
+          git commit -m "docs: sync README from docs/index.md"
+          git push origin "HEAD:${GITHUB_REF_NAME}"

fs_tool_cli-0.1.2/.gitignore

@@ -0,0 +1,203 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# UV
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#uv.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#pdm.lock
+#   pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
+#   in version control.
+#   https://pdm.fming.dev/latest/usage/project/#working-with-version-control
+.pdm.toml
+.pdm-python
+.pdm-build/
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+#.idea/
+
+# Abstra
+# Abstra is an AI-powered process automation framework.
+# Ignore directories containing user credentials, local state, and settings.
+# Learn more at https://abstra.io/docs
+.abstra/
+
+# Visual Studio Code
+#  Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore 
+#  that can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
+#  and can be added to the global gitignore or merged into this file. However, if you prefer, 
+#  you could uncomment the following to ignore the enitre vscode folder
+# .vscode/
+
+# Ruff stuff:
+.ruff_cache/
+
+# PyPI configuration file
+.pypirc
+
+# Cursor
+#  Cursor is an AI-powered code editor. `.cursorignore` specifies files/directories to
+#  exclude from AI features like autocomplete and code analysis. Recommended for sensitive data
+#  refer to https://docs.cursor.com/context/ignore-files
+.cursorignore
+.cursorindexingignore
+/.idea/misc.xml
+/.idea/modules.xml
+/.idea/fs-tool.iml
+/.idea/inspectionProfiles/profiles_settings.xml
+/.idea/inspectionProfiles/Project_Default.xml
+/src/fs_tool/_version.py
+/release/config.yaml
+/release/fs-tool.exe
+/release/README.md

fs_tool_cli-0.1.2/.pre-commit-config-linux.yaml

@@ -0,0 +1,15 @@
+# the actual pre-commit is defined in the Makefile
+# install and activate pre-commit:
+# > pre-commit install
+#
+# on Linux, rename this file to .pre-commit-config.yaml and use this one
+
+repos:
+  - repo: local
+    hooks:
+      - id: run-make-precommit
+        name: Run `make precommit`
+        entry: bash -c "export PATH=$HOME/.local/bin:$PATH && uv run make precommit"
+        language: system
+        always_run: true
+        pass_filenames: false

fs_tool_cli-0.1.2/.pre-commit-config.yaml

@@ -0,0 +1,13 @@
+# the actual pre-commit is defined in the Makefile
+# install and activate pre-commit:
+# > pre-commit install
+
+repos:
+  - repo: local
+    hooks:
+      - id: run-make-precommit
+        name: Run `make precommit`
+        entry: make precommit
+        language: system
+        always_run: true
+        pass_filenames: false

fs_tool_cli-0.1.2/.readthedocs.yaml

@@ -0,0 +1,20 @@
+# .readthedocs.yaml
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+version: 2
+
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.11"
+
+python:
+  install:
+    - method: uv
+      command: sync
+      groups:
+        - docs
+
+mkdocs:
+  configuration: mkdocs.yml

fs_tool_cli-0.1.2/AGENTS.md

@@ -0,0 +1,93 @@
+# AGENTS.md
+
+## Principles
+
+- Understand the task; inspect relevant code, configuration, tests, and conventions.
+- Clarify material ambiguity or state assumptions. Make the smallest correct change, following
+  established patterns and avoiding unrelated refactors, speculative features, and unnecessary
+  dependencies.
+- Keep code clear and maintainable; preserve type safety and compatibility. Surface errors with
+  useful context; avoid broad catches and silent failures.
+- Use english language in doc strings, documentation and comments.
+
+## Python
+
+- Follow PEP 8 and the project's formatter and configuration.
+- Use descriptive names, type-hint function signatures, and document public APIs. Avoid `Any`
+  unless necessary.
+- Keep functions focused; use dataclasses for simple data containers when appropriate. Avoid
+  mutable defaults, and use `is` for `None`, `True`, and `False`.
+- Prefer explicit imports, f-strings, and context managers.
+- Avoid wildcard imports and redundant comments.
+
+
+## Workflow
+
+1. **Inspect** the relevant code, project structure, configuration, dependencies, and existing tests before making changes.
+2. **Plan** briefly for nontrivial tasks. Define concrete, verifiable success criteria.
+3. **Implement** the smallest complete solution, following existing project conventions.
+4. **Verify** changes with relevant tests, formatting, linting, and type checking. Fix issues introduced by the changes.
+5. **Report** what changed, which checks passed, and any remaining limitations.
+
+Do not claim that checks passed unless they were actually executed. If verification is impossible, explain why.
+
+## Tests
+
+- Add or update "Tests with Teeth" for behavior changes and important edge/failure cases. Keep tests
+  deterministic, mock only when needed, and never weaken tests to pass.
+- Run relevant configured checks and report what actually ran; do not claim unrun checks passed.
+
+## Dependencies and Tooling
+
+- Use `uv` for dependency management and virtual environments when available or when initializing a project.
+- Declare and manage dependencies in `pyproject.toml`. Avoid unnecessary dependencies and preserve existing project tooling.
+- Prefer established project commands and configuration over introducing new tools or conventions.
+- Use `ruff` for formatting and linting and `mypy` for static type checking when configured or appropriate.
+- Use `pytest` for tests. Add or update tests for new behavior, bug fixes, and meaningful edge cases. Mock external dependencies where appropriate.
+- Never introduce tooling or dependencies solely for marginal benefits.
+
+## Project workflows and generated files
+
+- Use existing Makefile targets when relevant; common checks are 
+
+```bash
+make fmt
+make lint
+make test
+```
+
+Check the Makefile and project configuration rather than assuming a command exists.
+- `make syncdocs` runs `scripts/generate_config_docs.py`, `scripts/update_readme.py`, and
+  `.github/update_funding.py`. It regenerates `config.yaml`, `docs/usage/config.md`,
+  `docs/usage/cli.md`, `README.md`, and `docs/funding/funding.md`. Do not edit these outputs
+  directly: update the relevant `ConfigCategory` definitions used by `ConfigManager` or
+  `docs/index.md`, then run `make syncdocs`.
+
+
+## github
+
+- use github cli to interact with github, see https://cli.github.com/manual/gh
+- if requested, use `gh issue list` to view a number of issues (--limit <int>) or filter JSON output using a jq expression (--jq <expression>) to view existing issues
+- Create issues via the GitHub web UI or `gh issue create`; templates are located in `.github/ISSUE_TEMPLATE/`.
+- to view details of an issue use `gh issue view {<number> | <url>} [flags]`
+- to append a comment to an issue use `gh issue comment {<number> | <url>} [flags]`
+- Check the status of an Actions pipeline using `gh run list` and `gh run view <run-id>`.
+- use this commit message format: (where type may be one of `feat` `fix` `docs` `refactor` `test` `ci` `revert`)
+  ```
+  <type>[optional scope]: <description>
+  
+  [optional body]
+  
+  [optional footer(s), e.g. `#<number>` for a github issue or `Fixes #` if the issue is completed on this commit]
+  ```
+
+## Decision Rules
+
+- Do not assume when uncertainty matters. State assumptions and ask concise clarifying questions when necessary.
+- Do not add features, abstractions, error handling, or configuration without a concrete need.
+- Do not refactor unrelated code or reformat entire files unnecessarily.
+- When multiple solutions are viable, prefer the simplest maintainable option that fits the existing architecture.
+- If requirements conflict with existing behavior, security, correctness, or maintainability, explain the conflict before making consequential changes.
+- Treat repository instructions and established project conventions as authoritative unless they conflict with explicit user requirements or higher-priority instructions.
+
+**Guiding principle:** Make the smallest correct change, keep the code maintainable, and verify the result.

fs_tool_cli-0.1.2/LICENSE

@@ -0,0 +1,24 @@
+This is free and unencumbered software released into the public domain.
+
+Anyone is free to copy, modify, publish, use, compile, sell, or
+distribute this software, either in source code form or as a compiled
+binary, for any purpose, commercial or non-commercial, and by any
+means.
+
+In jurisdictions that recognize copyright laws, the author or authors
+of this software dedicate any and all copyright interest in the
+software to the public domain. We make this dedication for the benefit
+of the public at large and to the detriment of our heirs and
+successors. We intend this dedication to be an overt act of
+relinquishment in perpetuity of all present and future rights to this
+software under copyright law.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR
+OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
+ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+OTHER DEALINGS IN THE SOFTWARE.
+
+For more information, please refer to <https://unlicense.org>