Metadata-Version: 2.4
Name: pck-utils
Version: 0.1.0
Summary: A simple pair of Python utilities that 1. Encodes a project directory into a single JSON document. 2. Constructs or Reconstructs a project based on the JSON array describing the files and directories.
Author: Marlin Mixon
License: MIT License
        
        Copyright (c) [year] [fullname]
        
        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/marlin-mixon/pck
Project-URL: Repository, https://github.com/marlin-mixon/pck
Project-URL: Issues, https://github.com/marlin-mixon/pck/issues
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Environment :: Console
Classifier: Topic :: Software Development :: Build Tools
Classifier: Topic :: Utilities
Requires-Python: >=3.7
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# pck

A simple pair of Python utilities that 1. Packs a project directory into a single uncompressed JSON document.  2. Unpacks or reconstructs a project based on the JSON array describing the files and directories.

This tool makes it quick and easy to pass context to and from LLMs.  It is designed for AI-assisted development workflows where an LLM generates an entire project as structured JSON. The json_to_directory utility reads the JSON from **stdin** and recreates the corresponding directory structure and files on disk.  The directory_to_json reverses the process.  It creates a JSON file based on the contents of the starting directory and dives into the directory structure finding all files and stores them in a single JSON file.

## pck command Features

- Creates directories and files from a JSON document
- Automatically creates parent directories as needed
- Uses UTF-8 encoding
- Writes files with Unix (LF) line endings
- Refuses to overwrite existing files by default
- Lists all conflicting files before making any changes
- Supports `-f`, or `--force` options to force overwriting existing files
- Simple, dependency-free implementation using the Python standard library

## unpck command Features

- Creates two types of JSON files based on a directory structure.
- Default format type 1 is JSON array of objects.  This is easiest for humans to read and easily handled by LLMs
- This JSON format is a simple array and is only a single level deep.  Directory structure and depth is implied by the path elements.
- Writes JSON to STDOUT.  Redirect as needed


## JSON Format

Example of pck's JSON object format -- an array of JSON objects:

Each element contains:

- `path` – Relative path to a file or directory
- `content` – File contents (omitted or `null` for directories)
- `encoding` - Optional for identifying binary files.  Only valid entry is case-inensitive "base64".

```json
[
  {
    "path": "README.md",
    "content": "# My Project\n"
  },
  {
    "path": "src/",
    "content": null
  },
  {
    "path": "src/main.py",
    "content": "print('Hello, world!')\n"
  }.
  {
    "path": "assets/image.png",
    "encoding": "base64",
    "content": "iVBORw0KGgoAAAANSUhEUgAA..."
]
```

Directories are identified by a trailing `/`.  Note that defining directories in this way is optional and only required for creating empty directories.


## Usage

### Basic directory creation from a JSON file using JSON array of objects .pck file

```bash
Simple form:
unpck < project.pck

Provide optional subdirectory to unpack into.  If directory does not exist the path will be created:
unpck sub1/sub2 < project.pck
```

If existing files are found, the utility will stop before writing anything and display a list of conflicts.

Example:

```
ERROR: 4 existing files would be overwritten:

  README.md
  src/main.py
  src/utils.py
  requirements.txt

Nothing has been written.

Run again with -f to overwrite these files.
```
### As above but with force overwrite

```bash
unpck -f < project.pck

(use switches -f, --force as desired)
```

### Basic JSON creation from a directory structure

```bash
Simple form:
pck > project.pck

Provide optional starting directory:
pck sub1/sub2 > project2.pck
```

## Why this exists

Large Language Models often require full directory context in order to assist you in updating existing projects.  However, it can be a pain to hunt down, cut and paste the several files needed for context. The directory_to_json.py helps you do that in one command.  Conversely, when creating new projects like web sites or docker-compose projects, Large Language Models will typically generate a lot of documents that are a pain to copy and paste each into the appropriate directory structure without taking time plus you risk making mistakes. By first requesting the LLM to put the generated files into JSON and then using the json_t_directory.py you can solve this problem with a single command. These utilities provides a safe and simple way to pack and unpack your projects with adequate protections that protect existing work from accidental overwrites. 

## Requirements

- Python 3.7 or later
- No third-party dependencies

## Installation

```bash
pip install pck-utils
```

## License

MIT License
