Metadata-Version: 2.4
Name: tagmanager-cli
Version: 1.4.1
Summary: The Ultimate Command-Line File Tagging System - Transform chaos into order with intelligent file organization
Author-email: David Chincharashvili <david@example.com>
Maintainer-email: David Chincharashvili <david@example.com>
License: MIT
Project-URL: Homepage, https://github.com/davidtbilisi/TagManager
Project-URL: Documentation, https://github.com/davidtbilisi/TagManager#readme
Project-URL: Repository, https://github.com/davidtbilisi/TagManager.git
Project-URL: Bug Tracker, https://github.com/davidtbilisi/TagManager/issues
Project-URL: Changelog, https://github.com/davidtbilisi/TagManager/releases
Keywords: file-management,tagging,organization,cli,productivity,file-system,search,metadata
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Console
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.7
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: Topic :: System :: Filesystems
Classifier: Topic :: Utilities
Classifier: Topic :: System :: Systems Administration
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.7
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: typer>=0.9.0
Requires-Dist: rich>=10.0.0
Provides-Extra: watch
Requires-Dist: watchdog>=2.0.0; extra == "watch"
Provides-Extra: test
Requires-Dist: pytest>=7.0.0; extra == "test"
Requires-Dist: pytest-cov>=4.0.0; extra == "test"
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
Requires-Dist: black>=22.0.0; extra == "dev"
Requires-Dist: flake8>=5.0.0; extra == "dev"
Requires-Dist: watchdog>=2.0.0; extra == "dev"
Dynamic: license-file

# 🏷️ TagManager

<div align="center">

**The Ultimate Command-Line File Tagging System**

_Transform chaos into order with intelligent file organization_

[![PyPI](https://img.shields.io/pypi/v/tagmanager-cli.svg)](https://pypi.org/project/tagmanager-cli/)
[![Python](https://img.shields.io/badge/Python-3.7+-blue.svg)](https://python.org)
[![License](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
[![Platform](https://img.shields.io/badge/Platform-Windows%20%7C%20macOS%20%7C%20Linux-lightgrey.svg)](README.md)
[![Tests](https://img.shields.io/badge/Tests-406%20passed-brightgreen.svg)](tests/)

[Features](#-features) • [Installation](#-installation) • [Quick Start](#-quick-start) • [Commands](#-commands) • [Examples](#-examples)

</div>

---

## 🌟 Why TagManager?

Folder hierarchies force you to put a file in one place. Tags let a file belong to everything it actually is.

```bash
# One command to tag — one command to find
tm add report.pdf --tags work client-a q1 2024 final
tm search --tags work q1        # instantly surface it
```

TagManager stores tags in a lightweight JSON sidecar (`~/file_tags.json`) — no database, no daemon required — and ships a full command set for search, bulk operations, smart filtering, an interactive network graph, and a file-system watcher that tags new files automatically.

---

## ✨ Features

| Category | What you get |
|---|---|
| **Core** | Add/remove/search tags, fuzzy path search, list & tree views |
| **Bulk** | Mass-tag with glob patterns, retag, bulk-remove — all with `--dry-run` |
| **Auto-tag** | Extension-based tag suggestions (60+ file types built-in) |
| **Aliases** | Normalize tag variants: `py → python`, `js → javascript` |
| **Presets** | Save named tag bundles and apply them in one flag |
| **Filters** | Duplicate sets, orphans, similarity (Jaccard), clusters, isolated files |
| **Stats** | Tag frequency, co-occurrence, ASCII bar charts & histograms |
| **Visualizer** | Interactive 2D/3D network graph in your browser — click to open files |
| **Watch mode** | Auto-tag files the moment they land in a directory |
| **Move tracking** | `tm mv` keeps tag records in sync when you rename files |
| **Config** | Full dot-notation config system with export/import |
| **Shell completion** | Tab-complete tag names, presets, and alias names |

---

## 🚀 Installation

```bash
pip install tagmanager-cli
```

Commands are available as both `tm` (short) and `tagmanager` (long form).

### Optional: Watch mode

Watch mode requires [watchdog](https://pypi.org/project/watchdog/):

```bash
pip install tagmanager-cli[watch]
# or separately
pip install watchdog
```

### Install from source

```bash
git clone https://github.com/davidtbilisi/TagManager.git
cd TagManager
pip install -e .
```

---

## ⚡ Quick Start

```bash
# Tag a file (auto-tags by extension too)
tm add main.py --tags backend core

# Tag everything matching a glob
tm bulk add "src/**/*.py" --tags python

# Find files
tm search --tags backend core     # either tag
tm search --tags backend --match-all core  # both tags

# Visual overview
tm ls --tree
tm tags --cloud
tm stats --chart

# Interactive network graph (opens in browser)
tm graph

# Watch a directory — auto-tag as files arrive
tm watch ~/Downloads --tags inbox
```

---

## 📖 Commands

### `tm add` — Tag files

```bash
tm add <file> --tags <tag> [<tag>...]   # basic
tm add <file> --tags python --preset webproject  # combine with preset
tm add <file> --no-auto                 # skip extension-based auto-tags
tm add <file> --no-aliases              # skip alias resolution
```

### `tm search` — Find files

```bash
tm search --tags python web            # files with EITHER tag
tm search --tags python --match-all    # files with ALL listed tags
tm search --path /projects/            # by path fragment
tm search --tags python --exact        # exact tag match (no fuzzy)
```

### `tm ls` — List tagged files

```bash
tm ls           # flat table
tm ls --tree    # directory tree with inline tags
```

### `tm tags` — Explore tags

```bash
tm tags                  # list all tags
tm tags --search py      # filter tags by name
tm tags --cloud          # frequency cloud
tm tags --where python   # which files carry this tag
```

### `tm stats` — Analytics

```bash
tm stats              # summary
tm stats --chart      # ASCII bar charts
tm stats --tag python # deep-dive on one tag (co-occurrence, file types)
```

### `tm graph` — Interactive network visualizer

Opens a self-contained HTML graph in your default browser.

```bash
tm graph                        # tag co-occurrence graph, 2D
tm graph --3d                   # start in 3D (toggle button in UI too)
tm graph --mode file            # file similarity graph (Jaccard)
tm graph --mode mixed           # bipartite file↔tag graph
tm graph --export gexf          # also export tag_network.gexf (Gephi)
tm graph --export graphml       # for Cytoscape / yEd
tm graph --min-weight 2         # only show edges with ≥2 co-occurrences
tm graph --output ~/graph.html  # save to a specific path
```

**In the browser UI:**
- Sidebar with 10 live filters (search, tag/extension multi-select, weight & degree sliders, cluster highlight, color-by)
- 2D / 3D toggle — WebGL via Three.js, handles thousands of nodes
- Click any file node → opens it in your OS file explorer
- Download GEXF / GraphML buttons (embedded, no server needed)

### `tm watch` — Auto-tag new files

Monitors a directory with [watchdog](https://pypi.org/project/watchdog/) and tags files as they arrive.

```bash
tm watch                         # watch current dir
tm watch ~/Downloads             # watch a specific dir
tm watch . --tags inbox          # always add "inbox" to every new file
tm watch . --preset webproject   # apply a saved preset
tm watch . --no-auto             # skip extension auto-tagging
tm watch . --clean-on-delete     # remove tag entry when file is deleted
tm watch . --no-recursive        # top-level only
tm watch . --ignore "*.log"      # extra ignore patterns
tm watch . --plain               # plain text output (no Rich live display)
```

Rich live display shows a colour-coded event log (`✚ created`, `→ moved`, `✖ deleted`) with resolved tags. Press **Ctrl+C** to stop.

### `tm filter` — Smart analysis

```bash
tm filter duplicates             # files with identical tag sets
tm filter orphans                # files with no tags
tm filter similar <file>         # files similar to this one (Jaccard)
tm filter clusters               # group files by shared tag
tm filter isolated               # files that share few tags with others
```

### `tm bulk` — Mass operations

```bash
tm bulk add "*.py" --tags python          # tag by glob
tm bulk remove --tag deprecated           # remove a tag from all files
tm bulk retag --from js --to javascript   # rename a tag everywhere
# All bulk commands support --dry-run
```

### Aliases, Presets, Move tracking

```bash
# Aliases — normalize tag variants
tm alias add py python
tm alias list
tm alias remove py

# Presets — named tag bundles
tm preset save webproject --tags python django web
tm preset apply webproject app.py
tm preset list

# Move tracking — keep the DB in sync
tm mv old/path.py new/path.py
tm clean             # remove entries for deleted files
tm clean --dry-run   # preview
```

### Config

```bash
tm config list                         # all settings
tm config set display.emojis false
tm config set search.fuzzy_threshold 0.8
tm config export --file settings.json
tm config import team_settings.json
tm config reset                        # back to defaults
```

---

## 🎨 Examples

### Network graph

```
Tag co-occurrence network — 42 nodes, 180 edges
Sidebar filters: search · tag multiselect · min-weight slider · degree range
                 color-by cluster · highlight cluster · show/hide node types
2D ↔ 3D toggle  |  Download GEXF  |  Download GraphML
Click file node → opens in Finder/Explorer
```

### Watch mode output

```
Watching: /home/user/Downloads
  Recursive: True | Auto-tag: True | Clean-on-delete: False
  Always add tags: ['inbox']
Press Ctrl+C to stop.

[14:02:11] ✚ created ✓  report_q1.pdf  [inbox, pdf, document]
[14:02:45] ✚ created ✓  script.py      [inbox, python]
[14:03:10] → moved   ✓  script.py  →  processed/script.py
```

### Tag cloud

```
☁️  Tag Cloud
★ python(15)  ◆ web(8)  ● documentation(5)  • config(3)  · backup(1)
```

### Tree view

```
└── 📁 projects/
    ├── 📁 backend/
    │   └── 📄 api.py 🏷️  [python, web, api, core]
    └── 📁 docs/
        └── 📄 README.md 🏷️  [docs, markdown]
```

---

## 🏗️ Architecture

```
tagmanager/
├── cli.py                  # Typer CLI — all commands registered here
└── app/
    ├── add/                # tm add
    ├── bulk/               # tm bulk
    ├── filter/             # tm filter
    ├── search/             # tm search
    ├── stats/              # tm stats
    ├── graph/              # tm graph  (HTML generator, GEXF/GraphML export)
    ├── watch/              # tm watch  (watchdog integration)
    ├── alias/              # tm alias
    ├── preset/             # tm preset
    ├── autotag/            # extension → tag mappings
    ├── move/               # tm mv / tm clean
    ├── visualization/      # tree, cloud, ASCII charts
    ├── config/             # tm config
    └── helpers.py          # load_tags() / save_tags() — atomic JSON I/O
```

Storage: `~/file_tags.json` (path configurable). Plain JSON — easy to inspect, back up, or version-control.

---

## 🧪 Testing

```bash
pytest tests/ -v                           # full suite (406 tests)
pytest tests/ --cov=tagmanager             # with coverage
pytest tests/test_graph_service.py -v      # graph module only
pytest tests/test_watch_service.py -v      # watch module only
```

406 tests across 21 test files. Watch mode integration tests require `pip install watchdog`.

---

## 🤝 Contributing

1. Fork the repo
2. Create a feature branch
3. Add tests
4. Open a PR

Bug reports and feature requests: [GitHub Issues](https://github.com/davidtbilisi/TagManager/issues)

---

## 📄 License

MIT — see [LICENSE](LICENSE).

---

<div align="center">

**⭐ Star this repo if TagManager helps you stay organized!**

Made by [David Chincharashvili](https://github.com/DavidTbilisi) • Built with [Typer](https://typer.tiangolo.com/) and [Rich](https://github.com/Textualize/rich)

</div>
