cpsf_utilite/README.md

A CLI tool to generate a project's directory and file structure tree, with advanced filtering and configuration.

# cpsf_utilite

[![npm version](https://badge.fury.io/js/cpsf_utilite.svg)](https://badge.fury.io/js/cpsf_utilite)

**cpsf_utilite** (`Create Project Structure File`) is a powerful Command-Line Interface (CLI) tool that generates a project's directory structure tree. It is designed to be flexible, fast, and user-friendly, featuring smart filtering, content control, and full customization via a configuration file.

## Key Features

-   **Tree Generation:** Creates a clean, visual representation of your project's file and directory structure.
-   **Full Customization:** Control what gets included in the report using a `.structurerc.json` file.
-   **Smart Filtering:** Comes with extensive built-in lists to ignore unnecessary files and folders (like `node_modules`, `.git`, cache files, etc.).
-   **Content Control:** Option to display the content of text files or just the filenames for binary/media files.
-   **Large Directory Summaries:** Automatically collapses the contents of directories with thousands of similar files, showing only the beginning, end, and total count.
-   **Secret Hiding:** Automatically finds and hides API keys, passwords, and other secrets within file content.
-   **Git Integration:** Automatically updates your `.gitignore` to prevent generated files from being tracked in your repository.

## Installation

Install `cpsf_utilite` globally using npm:

```bash
npm install -g cpsf_utilite
```

## Getting Started

Using the utility involves two simple steps: initialization (once per project) and structure generation.

### Step 1: Initialization (Recommended)

In the root of your project, run the following command:

```bash
cpsf_utilite init
```

This command will do two things:
1.  Create a `.structurerc.json` file with default settings. You can now edit this file to customize the utility's behavior.
2.  Add the `project_copies/` directory and `.structurerc.json` to your `.gitignore` file.

### Step 2: Generating the Structure

After initialization, simply run the utility in your project's root directory:

```bash
cpsf_utilite
```

It will prompt you to choose an action in interactive mode. You can also specify the command directly:

```bash
cpsf_utilite structure
```

The result will be saved in the `project_copies/` directory in a file with a unique name, such as `project-structure_D_2023-10-27_H_15-30-00.txt`.

## Configuration (`.structurerc.json`)

All the customization magic happens in the `.structurerc.json` file. You can add or remove files, extensions, and folders to be ignored, included, or handled in a special way.

Here is an example configuration:
```json
{
  // Directories to be completely ignored
  "excludedDirectories": [".git", ".idea", "node_modules", "dist"],
  // Files to be completely ignored by name
  "excludedFiles": [".DS_Store", "yarn.lock"],
  // Files to be ignored by extension
  "excludedExtensions": [".log", ".env", ".bak"],
  // Files for which only the name is displayed (no content)
  "filesWithoutContent": ["package-lock.json", "README.md", ".py"],
  // Media extensions that do not have text content
  "mediaExtensions": [".png", ".jpg", ".mp3", ".zip"],
  // Regular expressions to find and hide secrets
  "secretsToHide": ["API_KEY=.*", "SECRET_TOKEN=.*"],
  // Settings for summarizing large directories
  "largeDirectorySummary": {
    "enabled": true,         // Enable/disable the feature
    "threshold": 10,         // File count threshold to consider a directory "large"
    "first": 3,              // How many files to show at the beginning
    "last": 3                // How many files to show at the end
  }
}
```

## Example Output

Thanks to the `largeDirectorySummary` feature, the output for projects with large datasets will be clean and informative:

```
.
└── data/
    ├── processed/
    │   ├── p225/
    │   │   ├── 001.pt
    │   │   ├── 002.pt
    │   │   ├── 003.pt
    │   │   ├── ... (and 360 more files) ...
    │   │   ├── 364.pt
    │   │   ├── 365.pt
    │   │   └── 366.pt
    │   └── p226/
    │       ├── 001.pt
    │       ├── 002.pt
    │       ├── 003.pt
    │       ├── ... (and 364 more files) ...
    │       ├── 368.pt
    │       ├── 369.pt
    │       └── 370.pt
    └── raw/
        └── VCTK-Corpus-0.92.zip
```

## FAQ

**Q: Can I customize which files and folders are ignored?**
A: Yes! That's the main advantage of this utility. Simply edit the `.structurerc.json` file created by the `cpsf_utilite init` command.

**Q: Can I use `cpsf_utilite` for non-Node.js projects?**
A: Absolutely. The utility operates on the file system and is not dependent on the project's technology stack.

## Feedback

If you have any questions or suggestions, please create an [Issue on GitHub](https://github.com/TechMaverickLab/cpsf_utilite/issues).

## License

`cpsf_utilite` is distributed under the MIT license.