archive

Archive

Four tools for .zip files: archive_list (what's inside), archive_read (one file out of it), archive_extract (unpack), archive_create (pack). They work in-process — no unzip or zip binary needed, same behaviour on macOS and Windows.

Look before you unpack

An archive is opaque until you list it, and unpacking is a side effect on the user's disk. So the order is always list → decide → act:

1. archive_list — cheap on any size, tells you what you're dealing with.
2. Decide with the user what they actually want (see below).
3. archive_read if the answer is inside one or two files; archive_extract if they want the files on disk.

Never claim to know what an archive contains without listing it first, and never describe files you have not read.

When the user uploads a zip and says nothing

This is the common case, and unpacking by default is the wrong move — you don't know whether they want it extracted, read, converted, inspected for one file, or sent somewhere. Do this instead:

1. archive_list it.
2. Tell them what's in there in one or two lines — the shape, not a file dump ("It's a 212-file React project — src/, public/, package.json, plus a 40 MB video in assets/").
3. Ask what they want done with it, and offer the obvious options for what you just saw ("Unpack it somewhere? Read a specific file? Convert the CSVs?"). Use ask_user when a short list of choices covers it.

Skip the question only when the request already answers it — "unzip this", "what's the README say", "pull the invoices out of this". Then just do it.

Reading vs extracting

archive_read answers questions; archive_extract puts files on the user's disk. Prefer reading: it's faster, leaves nothing behind, and is usually what a question about an archive actually needs. Extract when the user wants the files, when you need to run tools over many of them, or when a file is binary (archive_read will tell you so rather than dumping bytes).