zip-meta-map 0.2.2
Generate machine-readable metadata manifests for ZIP archives and project directories
Requires Python: >=3.11
Keywords: agent, ai, llm, manifest, metadata, navigation, zip

<p align="center">
  <img src="logo.png" alt="zip-meta-map logo" width="200">
</p>

<h1 align="center">zip-meta-map</h1>

<p align="center">
  <a href="https://github.com/mcp-tool-shop-org/zip-meta-map/actions/workflows/ci.yml"><img src="https://github.com/mcp-tool-shop-org/zip-meta-map/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
  <a href="https://pypi.org/project/zip-meta-map/"><img src="https://img.shields.io/pypi/v/zip-meta-map" alt="PyPI"></a>
  <a href="https://github.com/mcp-tool-shop-org/zip-meta-map/blob/main/LICENSE"><img src="https://img.shields.io/github/license/mcp-tool-shop-org/zip-meta-map" alt="License"></a>
  <img src="https://img.shields.io/badge/spec-v0.2-blue" alt="Spec v0.2">
  <img src="https://img.shields.io/badge/python-3.11%2B-blue" alt="Python 3.11+">
</p>

<p align="center">
Turn a ZIP or folder into a guided, LLM-friendly metadata bundle.<br>
<strong>Map + Route + Guardrails</strong> — inside the archive itself.
</p>

---

## What it does

zip-meta-map generates a deterministic metadata layer that answers three questions for AI agents:

- **What's in here?** — role-classified file inventory with confidence scores
- **What matters first?** — ranked start\_here list with excerpts
- **How do I navigate without drowning in context?** — traversal plans with byte budgets

## Quick demo

```bash
$ zip-meta-map build my-project/ -o output/ --summary

Wrote META_ZIP_FRONT.md and META_ZIP_INDEX.json to output/
  Profile:  python_cli
  Files:    47
  Modules:  8
  Flagged:  2 file(s) with risk flags
```

```bash
$ zip-meta-map explain my-project/

Profile:  python_cli
Files:    47

Top files to read first:
  README.md                     [doc]        conf=0.95  README is primary documentation
  src/app/main.py               [entrypoint] conf=0.95  matches profile entrypoint pattern
  pyproject.toml                [config]     conf=0.95  Python project configuration

Overview plan:
  Quick orientation — what is this tool and how is it structured?
  1. READ README.md for project purpose and usage
  2. READ pyproject.toml for dependencies and entry points
  3. READ entrypoint file to understand CLI structure
  Budget: ~32 KB
```

See the [golden demo output](examples/tiny_python_cli/) for a complete example.

## Install

```bash
pip install zip-meta-map
```

Or with [pipx](https://pipx.pypa.io/):

```bash
pipx install zip-meta-map
```

From source:

```bash
git clone https://github.com/mcp-tool-shop-org/zip-meta-map
cd zip-meta-map
pip install -e ".[dev]"
```

## GitHub Action

Use zip-meta-map in CI with the composite action:

```yaml
- name: Generate metadata map
  uses: mcp-tool-shop-org/zip-meta-map@v0
  with:
    path: .
```

This installs the tool, builds metadata, and writes a step summary. Outputs include `index-path`, `front-path`, `profile`, `file-count`, and `warnings-count`. Set `pr-comment: 'true'` to post the summary as a PR comment.

See [examples/github-action/](examples/github-action/) for a full workflow.

## What it generates

| File | Purpose |
|------|---------|
| `META_ZIP_FRONT.md` | Human-readable orientation page |
| `META_ZIP_INDEX.json` | Machine-readable index (roles, confidence, plans, chunks, excerpts, risk flags) |
| `META_ZIP_REPORT.md` | Detailed browseable report (with `--report md`) |

## CLI reference

```bash
# Build metadata for a folder or ZIP
zip-meta-map build path/to/repo -o output/
zip-meta-map build archive.zip -o output/

# Build with step summary and report
zip-meta-map build . -o output/ --summary --report md

# Output formats for piping
zip-meta-map build . --format json          # JSON to stdout
zip-meta-map build . --format ndjson        # one JSON line per file
zip-meta-map build . --manifest-only        # skip FRONT.md

# Explain what the tool detected
zip-meta-map explain path/to/repo
zip-meta-map explain path/to/repo --json

# Compare two indices (CI-friendly)
zip-meta-map diff old.json new.json             # human-readable
zip-meta-map diff old.json new.json --json       # JSON output
zip-meta-map diff old.json new.json --exit-code  # exit 1 if changes

# Validate an existing index
zip-meta-map validate META_ZIP_INDEX.json

# Policy overrides
zip-meta-map build . --policy META_ZIP_POLICY.json -o output/
```

## Profiles

Auto-detected by repo shape. Current built-ins:

| Profile | Detected by | Plans |
|---------|------------|-------|
| `python_cli` | `pyproject.toml`, `setup.py` | overview, debug, add\_feature, security\_review, deep\_dive |
| `node_ts_tool` | `package.json`, `tsconfig.json` | overview, debug, add\_feature, security\_review, deep\_dive |
| `monorepo` | `pnpm-workspace.yaml`, `lerna.json` | overview, debug, add\_feature, security\_review, deep\_dive |

See [docs/PROFILES.md](docs/PROFILES.md).

## Roles and confidence

Every file entry includes a **role** (bounded vocabulary), **confidence** (0.0–1.0), and **reason**.

| Band | Range | Meaning |
|------|-------|---------|
| High | >= 0.9 | Strong structural signal (filename match, profile entrypoint) |
| Good | >= 0.7 | Pattern match (directory convention, extension + location) |
| Fair | >= 0.5 | Extension-only or weak positional signal |
| Low  | < 0.5 | Assigned `unknown`; reason explains the ambiguity |

## Progressive disclosure (v0.2)

- **Chunk maps** for files > 32 KB — stable IDs, line ranges, headings
- **Module summaries** — directory-level role distribution and key files
- **Excerpts** — first few lines of high-value files
- **Risk flags** — exec\_shell, secrets\_like, network\_io, path\_traversal, binary\_masquerade, binary\_executable
- **Capabilities** — `capabilities[]` advertises which optional features are populated

## Stability

- Spec version follows semver-like rules: minor bumps add fields, major bumps break consumers
- `capabilities[]` is the official feature negotiation mechanism
- Older consumers that ignore unknown fields will continue to work across minor bumps
- See [docs/SPEC.md](docs/SPEC.md) for the full contract

## Repo structure

```
src/zip_meta_map/
  cli.py        # argparse CLI (build, explain, diff, validate)
  builder.py    # scan -> index -> validate -> write
  diff.py       # index comparison (diff command)
  report.py     # GitHub step summary + detailed report
  scanner.py    # directory + ZIP scanning with SHA-256
  roles.py      # role assignment heuristics + confidence
  profiles.py   # built-in profiles + traversal plans
  chunker.py    # deterministic text chunking
  modules.py    # folder-level module summaries
  safety.py     # risk flag detection + warning generation
  schema/       # JSON Schemas and loaders
docs/
  SPEC.md       # v0.2 contract (format semantics)
  PROFILES.md   # profile behaviors + plans
examples/
  tiny_python_cli/   # golden demo output
  github-action/     # consumer workflow example
tests/
  fixtures/     # tiny fixture repos
```

## Contributing

This project is small on purpose. If you contribute:

- keep heuristics deterministic
- keep roles bounded, push nuance into tags
- add tests for any new heuristic
- don't loosen schemas without updating docs/SPEC.md and goldens

```bash
pytest
```

## Documentation

- [Specification (v0.2)](docs/SPEC.md) — the contract for all generated files
- [Profiles](docs/PROFILES.md) — built-in project type profiles
- [Security](SECURITY.md) — vulnerability reporting

## License

MIT. See [LICENSE](LICENSE).