Text Directory Archiver

Text Directory Archiver

Serialize any directory structure into copyable plain text, or restore directories from text content. It can be operated automatically via scripts, and also acts as a multi-file delivery protocol between AI and users.

Quick Reference for Use Cases

Scenario Recommended Method

Local directory ↔ Text file (with terminal access) archive.py script

Request AI to generate a multi-file project AI outputs content following the protocol format

Migrate projects across sessions (no direct file transfer) Package to text → Paste into new session → Unpack

Share code repositories via instant messaging or forums Package to text; recipients unpack the content

Method 1: Automated Script (Terminal Environment Required)

Requirements: Python 3.6 or above; no extra packages required.

# Pack: Compress a directory into a text file
python archive.py pack <source_directory> <output_file.txt>

# Unpack: Restore a text file to a directory
python archive.py unpack <input_file.txt> <output_directory>

The script will automatically complete the following tasks:

· Embed plain text files (UTF-8 decodable) as raw content

· Encode binary files with Base64

· Record target paths for symbolic links (converted to placeholder files for cross-platform use)

· Generate a random separator to avoid content conflicts

Method 2: Direct AI Protocol Output (Pure Chat Environment)

Use this method when you need the AI to output a complete project structure during conversations.

Prompt Template for AI Output:

Output this project following the Text Directory Archiver protocol. Set the separator to 'v1', and include the files listed below: [List your files here]

Protocol Specifications

1. JSON Header (Must be placed at the very start)

{
  "separator": "v1",
  "files": {
    "src/main.py":   { "type": "text" },
    "README.md":     { "type": "text" },
    "data/model.bin":{ "type": "base64" },
    "logs/":         { "type": "dir" }
  }
}

· separator: A space‑free string for building delimiters to prevent conflicts with file content. A short random string is recommended.

· files: Declare all file paths. Valid type values: text, base64, dir, symlink.

1. File Content Blocks (Immediately after the JSON header)

---file_v1: src/main.py (text)
print("Hello, world!")

---file_v1: README.md (text)
# My Project
This is the documentation.

---file_v1: data/model.bin (base64)
SGVsbG8gV29ybGQ=

Format Rules:

· Each block starts with ---file_: () on an independent line

· Content continues until the next delimiter or the end of the text

· For symbolic links: Use ---symlink_: ->

· The dir type is only declared in the JSON header, with no corresponding content block

Minimal Example

{
  "separator": "x1",
  "files": {
    "hello.py": { "type": "text" },
    "assets/": { "type": "dir" }
  }
}
---file_x1: hello.py (text)
print("hi")

Notes

When Packing

· Large binary files (videos, model weights, etc.) will expand in size by approximately 33% due to Base64 encoding overhead. Exclude such files as appropriate.

· The script will skip symbolic links with missing targets and output a warning.

When Unpacking

· The target directory will be created automatically if it does not exist.

· Administrator privileges are required to create symbolic links on Windows. If creation fails, a placeholder file storing the link target path will be generated instead.

When Generating Content via AI

· Long outputs from AI may be truncated. Please check the integrity of the last file.

· For large projects, request the AI to output content in batches by directories.

Script Resources

scripts/archive.py: Core script that supports full packing and unpacking workflows, including processing for binary files and symbolic links. Run the script directly to view usage instructions.