Metadata-Version: 2.4
Name: dirmeta
Version: 0.1
Summary: A CLI tool to scan filesystem directory structures and view the captured metadata.
Author-email: Saptarshi Chakrabarti | LISCO <saptarshi.chakrabarti@kuleuven.be>
License: MIT License
        
        Copyright (c) 2025 Saptarshi Chakrabarti
        
        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.
        
Project-URL: Homepage, https://github.com/saptarshichakrabarti/dirmeta
Project-URL: Repository, https://github.com/saptarshichakrabarti/dirmeta
Keywords: filesystem,metadata,directory,scan,structure,tree,cli,utility,file management
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: End Users/Desktop
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.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
Requires-Python: >=3.7
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# DirMeta: Directory Metadata Scanner & Viewer

DirMeta is a command-line utility designed to scan filesystem directory structures, capture detailed metadata about files and folders, and provide both machine-readable (JSON) output saved to a file and a human-readable tree view loaded from that file. It's a general-purpose tool useful for documenting, understanding, or analyzing directory layouts.

## Features

*   **Recursive Scan:** Scans directories deeply to capture all nested files, folders, and symbolic links.
*   **Rich Metadata:** Collects essential information:
    *   Relative Path
    *   Type (file, folder, symlink)
    *   Permissions (standard string format)
    *   Size (for files)
    *   Timestamps (Modification, Access, Metadata Change, and Creation/Birth if available)
    *   File Extension (for files)
    *   Symlink Target (for symlinks)
*   **Direct JSON File Output:** The scanner (`structure-scan`) writes the collected metadata directly to a specified or automatically named JSON file.
*   **Tree Viewer:** The viewer (`structure-view`) loads a scan's JSON file and displays the structure as a formatted tree in the terminal, including key metadata for quick analysis.
*   **CLI Tools:** Installs two easy-to-use commands: `structure-scan` and `structure-view`.
*   **Configurable:** Options to include/exclude hidden files (`.` prefix) and specify the output file path.
*   **Pure Python:** Runs on Python >= 3.7 without requiring any external libraries.
*   **Cross-Platform:** Tested on Linux, macOS, and Windows.

## Installation

It is strongly recommended to install `dirmeta` within a Python virtual environment to avoid conflicts with system packages.

**1. Using pip**

```bash
pip install dirmeta
```

**2. Installing from Source (e.g., after cloning the repository)**

```bash
# Clone the repository (if needed)
# git clone <repository_url>
# cd dirmeta

# Create and activate a virtual environment (Python 3)
python3 -m venv .venv
source .venv/bin/activate  # On Windows use `.venv\Scripts\activate`

# Install the package
pip install .
```

## Usage

### 1. Scan a Directory (`structure-scan`)

The `structure-scan` command scans the specified directory path and **writes** the collected metadata as a JSON object to a file.

**Command:**

```bash
structure-scan [OPTIONS] ROOT_DIR
```

**Arguments:**

*   `ROOT_DIR`: The path to the directory you want to scan.

**Options:**

*   `-i`, `--include-hidden`: Include hidden files and directories (names starting with '.') in the scan. By default, they are excluded.
*   `-o FILE`, `--output FILE`: Specify the path for the output JSON file. **If omitted, defaults to `<ROOT_DIR_NAME>.json` saved in the directory *containing* `ROOT_DIR`**. For example, scanning `/path/to/mydata` would default to saving `/path/to/mydata.json`. Scanning `.` would default to saving `<CURRENT_DIR_NAME>.json` in the *parent* directory.
*   `-v`, `--verbose`: Enable debug logging (prints progress/warnings to `stderr`).

**Examples:**

```bash
# Scan the current directory (excluding hidden files).
# Output saved to '<CURRENT_DIR_NAME>.json' in the parent directory.
structure-scan .

# Scan '/var/log', including hidden files, save to 'log_scan.json' in the current directory
structure-scan --include-hidden --output log_scan.json /var/log

# Scan '~/my_project' verbosely.
# Output saved to '~/my_project.json' (assuming default output location).
structure-scan -v ~/my_project

# Scan 'data_folder' and save output inside it
structure-scan --output data_folder/scan_metadata.json data_folder
```

### 2. View Scan Results (`structure-view`)

The `structure-view` command reads a JSON file previously generated by `structure-scan` and displays the directory structure as a formatted tree in your terminal.

**Command:**

```bash
structure-view [OPTIONS] JSON_FILE
```

**Arguments:**

*   `JSON_FILE`: The path to the JSON file created by `structure-scan`.

**Options:**

*   `-v`, `--verbose`: Enable debug logging for the viewer (rarely needed).

**Examples:**

```bash
# View the scan results stored in 'project_scan.json'
structure-view project_scan.json

# View the log scan results
structure-view log_scan.json
```

### Example Output (`structure-view scan.json`)

```
Scan Root: /path/to/your/directory
Scan Timestamp: 2023-10-30T12:00:00Z
Schema Version: 1.0
------------------------------------------------------------
├── .gitattributes [F] -rw-r--r-- 60 B (Mod: ...)
├── LICENSE [F] -rw-r--r-- 1.1 KB (Cre: ... | Mod: ...)
# ... rest of tree structure ...
```
## Output JSON Schema (`structure-scan` output file)

The scanner produces a JSON object (written to the output file) with the following top-level keys:

*   `scanner_version`: Version string of the schema (e.g., "1.0" based on the provided script).
*   `scanned_path`: The absolute, resolved path of the directory that was scanned.
*   `timestamp_utc`: ISO 8601 timestamp (UTC, with `Z` suffix) indicating when the scan finished.
*   `items`: An array of objects, each representing a scanned file, folder, or symlink found within `scanned_path`.

Each object inside the `items` array contains the following fields:

*   `path` (String): Path relative to `scanned_path`, using `/` separators. The root directory itself is represented as `.`.
*   `type` (String): The type of the filesystem item: `"file"`, `"folder"`, or `"symlink"`.
*   `permissions` (String): Standard file mode string (e.g., `"drwxr-xr-x"`, `"-rw-r--r--"`).
*   `modified_utc` (String | Null): ISO 8601 timestamp (UTC) of last modification, or `null` if unavailable.
*   `accessed_utc` (String | Null): ISO 8601 timestamp (UTC) of last access, or `null` if unavailable.
*   `metadata_changed_utc` (String | Null): ISO 8601 timestamp (UTC) of last metadata change (Unix `ctime`), or `null` if unavailable.
*   `created_utc` (String | Null, Optional): ISO 8601 timestamp (UTC) of file creation/birth, if available on the platform/filesystem. Field may be absent if not found.
*   `size_bytes` (Integer, Optional): Size in bytes. Only present for `type: "file"`.
*   `file_extension` (String | Null, Optional): Lowercase file extension without the leading dot (e.g., `"txt"`, `"pdf"`). `null` if the file has no extension. Only present for `type: "file"`.
*   `symlink_target` (String | Null, Optional): The target path the symlink points to (can be relative or absolute). `null` if reading the target failed. Only present for `type: "symlink"`.

## License

This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.
