locals-filesystem 1.0.0__tar.gz

locals_filesystem-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Windows Monitor
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+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 OR COPYRIGHT HOLDERS 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.

locals_filesystem-1.0.0/PKG-INFO

@@ -0,0 +1,309 @@
+Metadata-Version: 2.4
+Name: locals_filesystem
+Version: 1.0.0
+Summary: Portable local file-system toolkit (CLI + interactive shell + Tkinter GUI) for Linux, Windows and macOS. Pure standard library, zero dependencies.
+Author: goldensakurazero
+License: MIT
+Keywords: filesystem,file-manager,file-search,duplicate-finder,checksum,archive,cross-platform,cli,gui,tkinter
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Environment :: Console
+Classifier: Environment :: X11 Applications
+Classifier: Environment :: Win32 (MS Windows)
+Classifier: Environment :: MacOS X
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: Intended Audience :: System Administrators
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Desktop Environment :: File Managers
+Classifier: Topic :: System :: Filesystems
+Classifier: Topic :: Utilities
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# fileforge
+
+A portable, **dependency-free** local file-system toolkit written in pure Python.
+Runs unchanged on **Linux**, **Windows** and **macOS** — command line, interactive
+shell **and a full graphical interface**.
+
+```
+ _____.__.__             _____
+_|__|  |  |  |   ____   / ____/___  ________  ____ ______   ____
+|  |  |  |  | _/ __ \ / /_  / __ \/ ___/ _ \/ __ `/ ___/ _ \_/ __ \
+|  |  |_|  |_|\  ___// __/ / /_/ / /  /  __/ /_/ / /  /  __/  ___/
+|__|____/____/ \___/ /_/    \____/_/   \___/\__, /_/   \___/\___/
+```
+
+---
+
+## Requirements
+
+* Python **3.8+** (tested on 3.12 / 3.13)
+* No third-party packages — only the standard library
+* The GUI needs `tkinter` (bundled with Windows/macOS Python and
+  `python3-tk` on Linux)
+* Works on Linux, Windows 10/11 and macOS
+
+## Quick start
+
+```bash
+# from the repository
+python fileforge.py --help                 # list all commands
+python fileforge.py gui                    # graphical interface
+python fileforge.py shell                  # interactive shell
+python -m fileforge ls -l .                # run as a module
+```
+
+## Install as a pip package
+
+The project ships as a wheel (`dist/fileforge_toolkit-1.0.0-py3-none-any.whl`):
+
+```bash
+pip install dist/fileforge_toolkit-1.0.0-py3-none-any.whl
+```
+
+After installation two commands are available everywhere:
+
+```bash
+fileforge --version        # CLI (all 40+ commands)
+fileforge shell            # interactive shell
+fileforge-gui              # graphical interface (no console window)
+fileforge gui              # GUI via the CLI entry point
+```
+
+To publish to PyPI (once you own the name):
+
+```bash
+python -m build            # rebuild dist/
+twine upload dist/*
+```
+
+To build from source: `pip install build && python -m build`.
+
+---
+
+## Command reference
+
+### Navigation & listing
+
+| Command | Description |
+|---|---|
+| `ls [path] [-l] [-a] [--sort name\|size\|time\|ext]` | List directory contents |
+| `tree [path] [-L depth] [-a] [--no-size]` | ASCII directory tree with sizes |
+| `stat <path> [--json]` | Detailed metadata (mode, times, inode, counts, MIME) |
+| `filetype <path>` | Content-based MIME detection |
+| `free [path]` | Free / used / total space on a volume |
+
+### File content
+
+| Command | Description |
+|---|---|
+| `cat <path> [-n] [--head N] [--tail N] [--encoding ENC]` | Print a text file |
+| `write <path> (-c TEXT \| -f FILE \| --stdin) [-a] [--newline]` | Write or append |
+| `touch <path>` | Create an empty file / bump mtime |
+| `wc <path>` | Count lines, words, chars, bytes |
+| `replace <path> OLD NEW [--regex] [-i] [--dry-run]` | In-place text replace |
+| `convert-encoding <path> --to ENC [--from ENC] [-o OUT]` | Transcode a text file |
+
+### File & directory management
+
+| Command | Description |
+|---|---|
+| `cp <src> <dest> [--overwrite] [--no-recursive] [--no-preserve]` | Copy file/dir |
+| `mv <src> <dest> [--overwrite]` | Move or rename |
+| `rm <path> [-r] [-f] [--secure] [--passes N]` | Remove (optionally shred) |
+| `mkdir <path> [--no-parents] [--exist-ok]` | Create directories |
+| `rename <path> <new_name>` | Rename one path |
+| `rename-batch <paths...> --pattern P --replacement R [--regex] [-i] [--dry-run]` | Batch rename |
+| `symlink <target> <link>` / `readlink <path>` | Symbolic links |
+
+### Search
+
+| Command | Description |
+|---|---|
+| `find [root] [-name GLOB] [--regex RE] [--ext .py] [--min-size 1k] [--max-size 10M] [--newer 7d] [--older 30d] [--content TEXT] [--files-only] [--dirs-only] [--empty] [--depth N] [-a] [-l] [--limit N]` | Multi-criteria search |
+| `grep <pattern> [paths...] [--regex] [-s] [--include GLOB] [--exclude GLOB] [--no-recursive] [--max N]` | Search text inside files |
+
+Size accepts `B, K/KB, M/MB, G/GB, T/TB`. Duration accepts `s, m, h, d, w`
+(e.g. `7d`, `12h`, `3d12h`).
+
+### Integrity
+
+| Command | Description |
+|---|---|
+| `hash <paths...> [-a ALGO] [-r]` | Checksums (md5, sha1/224/256/384/512, blake2b/s) |
+| `manifest <root> [-a ALGO] [-o OUT]` | Create a JSON checksum manifest |
+| `verify <manifest> [--extra]` | Verify files against a manifest |
+| `compare <a> <b> [-a ALGO]` | Compare two files, report first differing byte |
+| `dupes <root> [-a ALGO] [--min-size SIZE] [--hidden]` | Find duplicate files |
+
+### Analytics
+
+| Command | Description |
+|---|---|
+| `du [root] [--top N] [--no-hidden]` | Disk-usage breakdown by extension / top-level |
+| `largest [root] [--limit N]` | Largest files |
+| `newest [root] [--limit N]` / `oldest [root] [--limit N]` | By modification time |
+| `empty [root]` | Empty files and directories |
+| `broken-links [root]` | Broken symbolic links |
+| `ext-summary [root]` | Per-extension file count and size |
+| `summary [root]` | One-shot full report |
+
+### Archives, split & sync
+
+| Command | Description |
+|---|---|
+| `archive-create <output> <sources...> [--format zip\|tar] [--base-dir DIR]` | Create zip / tar / tar.gz / tar.bz2 / tar.xz |
+| `archive-extract <archive> [-d DEST] [--member NAME]` | Extract (zip-slip protected) |
+| `archive-list <archive>` | List entries |
+| `gzip <path> [-d] [-k]` | Single-file gzip / gunzip |
+| `split <path> --size 10M [--out-dir D]` | Split a file into parts |
+| `merge <output> <parts...>` | Merge parts back |
+| `sync <src> <dest> [--delete] [--dry-run]` | Incremental directory mirror |
+
+### Permissions & security
+
+| Command | Description |
+|---|---|
+| `chmod <path> <mode> [-r]` | Octal (`644`) or symbolic (`+x`, `u+rw`, `go-w`) |
+| `perms [path] [-r]` | Show permission strings |
+| `world-writable [root]` | Audit world-writable entries |
+| `shred <path> [--passes N]` | Overwrite then delete a file |
+| `encrypt <path> [-p PWD] [-o OUT] [--remove-source]` | Encrypt to `.ffenc` |
+| `decrypt <path> [-p PWD] [-o OUT] [--remove-source]` | Decrypt `.ffenc` |
+
+---
+
+## Graphical interface
+
+```bash
+python fileforge.py gui      # or: fileforge-gui after pip install
+```
+
+A single window with a directory tree on the left and eight tool tabs:
+
+| Tab | What you can do |
+|---|---|
+| **Browser** | Navigate, sort, copy/move/rename/delete/shred, properties, hash, archive, encrypt, open terminal or file manager, context menu |
+| **Search** | All find criteria (glob, regex, ext, size, age, content, empty, depth) with a results table and right-click actions |
+| **Grep** | Recursive text search with include/exclude filters; double-click jumps to the line in the built-in viewer |
+| **Integrity** | Hash any file, compare two files, create/verify manifests, find duplicates and delete the extra copies |
+| **Archive** | Create/extract/inspect zip & tar archives, gzip, split files into parts, merge parts back, incremental folder sync |
+| **Analytics** | Summary report, extension breakdown with a bar chart, largest/newest/oldest files, empty items, broken links |
+| **Security** | Encrypt/decrypt with password, shred, chmod (octal + symbolic), permission listing, world-writable audit |
+| **Text Tools** | View and edit files, save, word count, regex replace with dry-run, encoding conversion |
+
+Extras: light/dark minimal theme toggle, hidden-files toggle, `F5` refresh,
+status bar with live free space, all long jobs run on background threads.
+
+## Interactive shell
+
+```bash
+python fileforge.py shell
+```
+
+```
+ff:D:\projects> ls
+ff:D:\projects> cd src
+ff:D:\projects\src> find . --ext .py -l
+ff:D:\projects\src> summary .
+ff:D:\projects\src> !dir                 # run any native shell command
+ff:D:\projects\src> exit
+```
+
+Builtins: `cd`, `pwd`, `help`, `history`, `clear`, `exit` / `quit`,
+and `!<command>` to pass through to the system shell. **Every CLI command is
+available inside the shell with identical options.**
+
+---
+
+## Example workflows
+
+```bash
+# Find Python files changed in the last 3 days and check their hashes
+python fileforge.py find . --ext .py --newer 3d -l
+python fileforge.py hash ./src -a sha256 -r
+
+# Reclaim disk space: find duplicates and large files
+python fileforge.py dupes ~/Downloads
+python fileforge.py largest ~/Videos --limit 10
+
+# Back up a project as a tar.gz and record a checksum manifest
+python fileforge.py archive-create backup.tar.gz ./project
+python fileforge.py manifest ./project -o ./project/manifest.json
+python fileforge.py verify ./project/manifest.json --extra
+
+# Batch-rename screenshots IMG_1234.png -> photo_1234.png
+python fileforge.py rename-batch ~/Pictures/*.png --pattern IMG_ --replacement photo_ --dry-run
+
+# Split a large file for transfer, then merge it back
+python fileforge.py split big.iso --size 100M --out-dir ./parts
+python fileforge.py merge big.iso ./parts/*
+
+# Mirror a folder, removing files deleted at the source
+python fileforge.py sync ./site ./backup/site --delete
+```
+
+---
+
+## Design notes
+
+* **Pure stdlib** — no `pip install` required; copies of this folder run anywhere.
+* **Safety first** — extraction guards against path traversal; `--dry-run`
+  is available for rename, replace and sync.
+* **Structured core** — `fileforge/*.py` modules (`core`, `search`, `hashutil`,
+  `archive`, `analytics`, `security`, `utils`) can be imported and reused as a
+  library:
+
+```python
+from fileforge import core, search, hashutil
+
+core.write_text("notes.txt", "hello\n")
+print(hashutil.hash_file("notes.txt", "sha256"))
+for e in search.find(search.FindCriteria(root=".", extensions=[".py"])):
+    print(e.rel, e.size)
+```
+
+* **Custom encryption caveat** — `encrypt` / `decrypt` use a self-contained
+  PBKDF2 + SHA-256 stream cipher with an HMAC tag. It is dependency-free and
+  fine for personal obfuscation, but it is **not audited cryptography**. For
+  sensitive data prefer `age`, `gpg` or `openssl`.
+
+---
+
+## Project layout
+
+```
+localfilessystem/
+├── fileforge.py            # single-file launcher
+├── README.md
+└── fileforge/
+    ├── __init__.py
+    ├── __main__.py         # enables `python -m fileforge`
+    ├── cli.py              # argparse dispatcher + all command impls
+    ├── gui.py              # Tkinter graphical interface
+    ├── repl.py             # interactive shell
+    ├── core.py             # file/dir operations, tree, stat, text tools
+    ├── search.py           # find + grep + size/duration parsing
+    ├── hashutil.py         # hashes, manifest, verify, duplicates, compare
+    ├── archive.py          # zip/tar/gzip, split/merge, sync
+    ├── analytics.py        # du, largest/newest, empty, broken links
+    ├── security.py         # chmod, shred, encryption
+    └── utils.py            # shared helpers, platform detection, output
+```
+
+
+## License
+
+MIT

locals_filesystem-1.0.0/README.md

@@ -0,0 +1,276 @@
+# fileforge
+
+A portable, **dependency-free** local file-system toolkit written in pure Python.
+Runs unchanged on **Linux**, **Windows** and **macOS** — command line, interactive
+shell **and a full graphical interface**.
+
+```
+ _____.__.__             _____
+_|__|  |  |  |   ____   / ____/___  ________  ____ ______   ____
+|  |  |  |  | _/ __ \ / /_  / __ \/ ___/ _ \/ __ `/ ___/ _ \_/ __ \
+|  |  |_|  |_|\  ___// __/ / /_/ / /  /  __/ /_/ / /  /  __/  ___/
+|__|____/____/ \___/ /_/    \____/_/   \___/\__, /_/   \___/\___/
+```
+
+---
+
+## Requirements
+
+* Python **3.8+** (tested on 3.12 / 3.13)
+* No third-party packages — only the standard library
+* The GUI needs `tkinter` (bundled with Windows/macOS Python and
+  `python3-tk` on Linux)
+* Works on Linux, Windows 10/11 and macOS
+
+## Quick start
+
+```bash
+# from the repository
+python fileforge.py --help                 # list all commands
+python fileforge.py gui                    # graphical interface
+python fileforge.py shell                  # interactive shell
+python -m fileforge ls -l .                # run as a module
+```
+
+## Install as a pip package
+
+The project ships as a wheel (`dist/fileforge_toolkit-1.0.0-py3-none-any.whl`):
+
+```bash
+pip install dist/fileforge_toolkit-1.0.0-py3-none-any.whl
+```
+
+After installation two commands are available everywhere:
+
+```bash
+fileforge --version        # CLI (all 40+ commands)
+fileforge shell            # interactive shell
+fileforge-gui              # graphical interface (no console window)
+fileforge gui              # GUI via the CLI entry point
+```
+
+To publish to PyPI (once you own the name):
+
+```bash
+python -m build            # rebuild dist/
+twine upload dist/*
+```
+
+To build from source: `pip install build && python -m build`.
+
+---
+
+## Command reference
+
+### Navigation & listing
+
+| Command | Description |
+|---|---|
+| `ls [path] [-l] [-a] [--sort name\|size\|time\|ext]` | List directory contents |
+| `tree [path] [-L depth] [-a] [--no-size]` | ASCII directory tree with sizes |
+| `stat <path> [--json]` | Detailed metadata (mode, times, inode, counts, MIME) |
+| `filetype <path>` | Content-based MIME detection |
+| `free [path]` | Free / used / total space on a volume |
+
+### File content
+
+| Command | Description |
+|---|---|
+| `cat <path> [-n] [--head N] [--tail N] [--encoding ENC]` | Print a text file |
+| `write <path> (-c TEXT \| -f FILE \| --stdin) [-a] [--newline]` | Write or append |
+| `touch <path>` | Create an empty file / bump mtime |
+| `wc <path>` | Count lines, words, chars, bytes |
+| `replace <path> OLD NEW [--regex] [-i] [--dry-run]` | In-place text replace |
+| `convert-encoding <path> --to ENC [--from ENC] [-o OUT]` | Transcode a text file |
+
+### File & directory management
+
+| Command | Description |
+|---|---|
+| `cp <src> <dest> [--overwrite] [--no-recursive] [--no-preserve]` | Copy file/dir |
+| `mv <src> <dest> [--overwrite]` | Move or rename |
+| `rm <path> [-r] [-f] [--secure] [--passes N]` | Remove (optionally shred) |
+| `mkdir <path> [--no-parents] [--exist-ok]` | Create directories |
+| `rename <path> <new_name>` | Rename one path |
+| `rename-batch <paths...> --pattern P --replacement R [--regex] [-i] [--dry-run]` | Batch rename |
+| `symlink <target> <link>` / `readlink <path>` | Symbolic links |
+
+### Search
+
+| Command | Description |
+|---|---|
+| `find [root] [-name GLOB] [--regex RE] [--ext .py] [--min-size 1k] [--max-size 10M] [--newer 7d] [--older 30d] [--content TEXT] [--files-only] [--dirs-only] [--empty] [--depth N] [-a] [-l] [--limit N]` | Multi-criteria search |
+| `grep <pattern> [paths...] [--regex] [-s] [--include GLOB] [--exclude GLOB] [--no-recursive] [--max N]` | Search text inside files |
+
+Size accepts `B, K/KB, M/MB, G/GB, T/TB`. Duration accepts `s, m, h, d, w`
+(e.g. `7d`, `12h`, `3d12h`).
+
+### Integrity
+
+| Command | Description |
+|---|---|
+| `hash <paths...> [-a ALGO] [-r]` | Checksums (md5, sha1/224/256/384/512, blake2b/s) |
+| `manifest <root> [-a ALGO] [-o OUT]` | Create a JSON checksum manifest |
+| `verify <manifest> [--extra]` | Verify files against a manifest |
+| `compare <a> <b> [-a ALGO]` | Compare two files, report first differing byte |
+| `dupes <root> [-a ALGO] [--min-size SIZE] [--hidden]` | Find duplicate files |
+
+### Analytics
+
+| Command | Description |
+|---|---|
+| `du [root] [--top N] [--no-hidden]` | Disk-usage breakdown by extension / top-level |
+| `largest [root] [--limit N]` | Largest files |
+| `newest [root] [--limit N]` / `oldest [root] [--limit N]` | By modification time |
+| `empty [root]` | Empty files and directories |
+| `broken-links [root]` | Broken symbolic links |
+| `ext-summary [root]` | Per-extension file count and size |
+| `summary [root]` | One-shot full report |
+
+### Archives, split & sync
+
+| Command | Description |
+|---|---|
+| `archive-create <output> <sources...> [--format zip\|tar] [--base-dir DIR]` | Create zip / tar / tar.gz / tar.bz2 / tar.xz |
+| `archive-extract <archive> [-d DEST] [--member NAME]` | Extract (zip-slip protected) |
+| `archive-list <archive>` | List entries |
+| `gzip <path> [-d] [-k]` | Single-file gzip / gunzip |
+| `split <path> --size 10M [--out-dir D]` | Split a file into parts |
+| `merge <output> <parts...>` | Merge parts back |
+| `sync <src> <dest> [--delete] [--dry-run]` | Incremental directory mirror |
+
+### Permissions & security
+
+| Command | Description |
+|---|---|
+| `chmod <path> <mode> [-r]` | Octal (`644`) or symbolic (`+x`, `u+rw`, `go-w`) |
+| `perms [path] [-r]` | Show permission strings |
+| `world-writable [root]` | Audit world-writable entries |
+| `shred <path> [--passes N]` | Overwrite then delete a file |
+| `encrypt <path> [-p PWD] [-o OUT] [--remove-source]` | Encrypt to `.ffenc` |
+| `decrypt <path> [-p PWD] [-o OUT] [--remove-source]` | Decrypt `.ffenc` |
+
+---
+
+## Graphical interface
+
+```bash
+python fileforge.py gui      # or: fileforge-gui after pip install
+```
+
+A single window with a directory tree on the left and eight tool tabs:
+
+| Tab | What you can do |
+|---|---|
+| **Browser** | Navigate, sort, copy/move/rename/delete/shred, properties, hash, archive, encrypt, open terminal or file manager, context menu |
+| **Search** | All find criteria (glob, regex, ext, size, age, content, empty, depth) with a results table and right-click actions |
+| **Grep** | Recursive text search with include/exclude filters; double-click jumps to the line in the built-in viewer |
+| **Integrity** | Hash any file, compare two files, create/verify manifests, find duplicates and delete the extra copies |
+| **Archive** | Create/extract/inspect zip & tar archives, gzip, split files into parts, merge parts back, incremental folder sync |
+| **Analytics** | Summary report, extension breakdown with a bar chart, largest/newest/oldest files, empty items, broken links |
+| **Security** | Encrypt/decrypt with password, shred, chmod (octal + symbolic), permission listing, world-writable audit |
+| **Text Tools** | View and edit files, save, word count, regex replace with dry-run, encoding conversion |
+
+Extras: light/dark minimal theme toggle, hidden-files toggle, `F5` refresh,
+status bar with live free space, all long jobs run on background threads.
+
+## Interactive shell
+
+```bash
+python fileforge.py shell
+```
+
+```
+ff:D:\projects> ls
+ff:D:\projects> cd src
+ff:D:\projects\src> find . --ext .py -l
+ff:D:\projects\src> summary .
+ff:D:\projects\src> !dir                 # run any native shell command
+ff:D:\projects\src> exit
+```
+
+Builtins: `cd`, `pwd`, `help`, `history`, `clear`, `exit` / `quit`,
+and `!<command>` to pass through to the system shell. **Every CLI command is
+available inside the shell with identical options.**
+
+---
+
+## Example workflows
+
+```bash
+# Find Python files changed in the last 3 days and check their hashes
+python fileforge.py find . --ext .py --newer 3d -l
+python fileforge.py hash ./src -a sha256 -r
+
+# Reclaim disk space: find duplicates and large files
+python fileforge.py dupes ~/Downloads
+python fileforge.py largest ~/Videos --limit 10
+
+# Back up a project as a tar.gz and record a checksum manifest
+python fileforge.py archive-create backup.tar.gz ./project
+python fileforge.py manifest ./project -o ./project/manifest.json
+python fileforge.py verify ./project/manifest.json --extra
+
+# Batch-rename screenshots IMG_1234.png -> photo_1234.png
+python fileforge.py rename-batch ~/Pictures/*.png --pattern IMG_ --replacement photo_ --dry-run
+
+# Split a large file for transfer, then merge it back
+python fileforge.py split big.iso --size 100M --out-dir ./parts
+python fileforge.py merge big.iso ./parts/*
+
+# Mirror a folder, removing files deleted at the source
+python fileforge.py sync ./site ./backup/site --delete
+```
+
+---
+
+## Design notes
+
+* **Pure stdlib** — no `pip install` required; copies of this folder run anywhere.
+* **Safety first** — extraction guards against path traversal; `--dry-run`
+  is available for rename, replace and sync.
+* **Structured core** — `fileforge/*.py` modules (`core`, `search`, `hashutil`,
+  `archive`, `analytics`, `security`, `utils`) can be imported and reused as a
+  library:
+
+```python
+from fileforge import core, search, hashutil
+
+core.write_text("notes.txt", "hello\n")
+print(hashutil.hash_file("notes.txt", "sha256"))
+for e in search.find(search.FindCriteria(root=".", extensions=[".py"])):
+    print(e.rel, e.size)
+```
+
+* **Custom encryption caveat** — `encrypt` / `decrypt` use a self-contained
+  PBKDF2 + SHA-256 stream cipher with an HMAC tag. It is dependency-free and
+  fine for personal obfuscation, but it is **not audited cryptography**. For
+  sensitive data prefer `age`, `gpg` or `openssl`.
+
+---
+
+## Project layout
+
+```
+localfilessystem/
+├── fileforge.py            # single-file launcher
+├── README.md
+└── fileforge/
+    ├── __init__.py
+    ├── __main__.py         # enables `python -m fileforge`
+    ├── cli.py              # argparse dispatcher + all command impls
+    ├── gui.py              # Tkinter graphical interface
+    ├── repl.py             # interactive shell
+    ├── core.py             # file/dir operations, tree, stat, text tools
+    ├── search.py           # find + grep + size/duration parsing
+    ├── hashutil.py         # hashes, manifest, verify, duplicates, compare
+    ├── archive.py          # zip/tar/gzip, split/merge, sync
+    ├── analytics.py        # du, largest/newest, empty, broken links
+    ├── security.py         # chmod, shred, encryption
+    └── utils.py            # shared helpers, platform detection, output
+```
+
+
+## License
+
+MIT

locals_filesystem-1.0.0/fileforge/__init__.py

@@ -0,0 +1,24 @@
+"""
+fileforge
+=========
+
+A portable, dependency-free local file-system toolkit for Linux, Windows
+and macOS. It bundles file / directory management, search, integrity
+checking, archives, permissions, security helpers and tree analytics
+behind a single command line (and an interactive shell).
+
+Quick start
+-----------
+    python fileforge.py --help
+    python fileforge.py ls -l .
+    python fileforge.py find . --ext .py --newer 7d
+    python fileforge.py summary .
+    python fileforge.py shell
+"""
+
+from __future__ import annotations
+
+from .utils import FileForgeError
+
+__version__ = "1.0.0"
+__all__ = ["FileForgeError", "__version__"]

locals_filesystem-1.0.0/fileforge/__main__.py

@@ -0,0 +1,9 @@
+"""Allow `python -m fileforge ...`."""
+from __future__ import annotations
+
+import sys
+
+from .cli import main
+
+if __name__ == "__main__":
+    sys.exit(main())