57 lines
2.5 KiB
Markdown
57 lines
2.5 KiB
Markdown
---
|
|
name: bundle-zip
|
|
description: Use when Codex needs to create a zip archive from an explicit file list while preserving source-relative paths, especially for GPT/CCRA review bundles, handoff packages, changed-file bundles, or Windows-safe packaging where PowerShell Compress-Archive may flatten paths. Use for newline-delimited file lists, root-marker-based zip entry names, overwrite-safe zip creation, and zip readback validation.
|
|
---
|
|
|
|
# Bundle Zip
|
|
|
|
## Purpose
|
|
|
|
Create a zip archive from an explicit newline-delimited file list while preserving paths relative to a named root path segment. Use the bundled Python script instead of PowerShell `Compress-Archive` when exact zip entry names matter.
|
|
|
|
The script uses Python standard-library `zipfile`; it does not implement compression itself.
|
|
|
|
## Command
|
|
|
|
Run from the repository or working directory that should resolve relative file-list entries:
|
|
|
|
```powershell
|
|
conda run -n skills-vault python .\scripts\bundle_zip.py `
|
|
--file-list C:\path\files.txt `
|
|
--relative-root-marker repo-name `
|
|
--output C:\path\bundle.zip `
|
|
--verify `
|
|
--json
|
|
```
|
|
|
|
If the Skill is installed under `C:\Users\wangq\.agents\skills\bundle-zip`, use that installed script path or run from the installed Skill directory.
|
|
|
|
## Inputs
|
|
|
|
- `--file-list`: UTF-8 text file with one source file per line. Blank lines are ignored.
|
|
- `--relative-root-marker`: exact path segment that defines where zip entry names start. If a source path contains the marker zero times or more than once, fail.
|
|
- `--output`: destination zip path. The parent directory must already exist.
|
|
- `--verify`: accepted for explicit workflows; readback verification is always performed.
|
|
- `--json`: print machine-readable summary JSON to stdout.
|
|
- `--json-output`: optionally write the same validation summary to a JSON file.
|
|
|
|
File-list entries may be absolute paths or paths relative to the current working directory. Zip entry names always use `/`.
|
|
|
|
## Safety
|
|
|
|
- Validate all sources before replacing an existing output zip.
|
|
- Reject missing files, directories, duplicate zip entries, and an output path that is also a source file.
|
|
- Package only explicitly listed files; do not recursively package directories.
|
|
- Write a temporary zip next to the output, verify it, then replace the requested output zip.
|
|
- Do not modify source files.
|
|
|
|
## Validation
|
|
|
|
After editing the script, run:
|
|
|
|
```powershell
|
|
conda run -n skills-vault python -B -m unittest discover -s skills/bundle-zip/tests -v
|
|
```
|
|
|
|
For full repository confidence, also run relevant neighboring Skill tests when shared code or install behavior changes.
|