# 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.
