Metadata-Version: 2.4
Name: dirpluck
Version: 0.9.0
Summary: Select files from declared runtime and fixed sources and package them into ZIP archives.
Author: minoru_jp
License-Expression: MIT
Keywords: llm,developer-tools,file-selection,directory,cli,toml,zip
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Operating System :: OS Independent
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# dirpluck

`dirpluck` is a tool that records decisions about which files belong together in TOML and builds a ZIP Archive from that declaration. The CLI is the primary entry point, and the same invocation model is also available through a small Python API.

Rather than copying everything around it like a backup, it is intended to repeatedly gather only the files needed for a particular purpose, such as review, handoff, research, recurring work, or a working context handled with an LLM.

## Where it fits

### Gather the material you need into one Archive

Material spread across multiple directories can be collected into one Archive when it serves the same purpose.

For example, a review package might bring together:

- the source of the project being reviewed
- review guidelines
- reference material

You can gather only fixed material, or attach fixed material to a Target selected at runtime.

### Apply the same extraction to different Targets

If you record decisions such as "collect README, `src/`, and `tests/`" or "exclude secrets and generated files" in a Configuration, you can reuse the same rules while changing the project being handled.

The Scope from which a Target is selected is defined separately, so the Configuration and the actual project tree do not need to live in the same place.

## Why keep it declarative

For a one-off task, creating a ZIP by hand may be simpler.

`dirpluck` is useful when the same kind of decision needs to be made again later.

A Configuration lets you record:

- what must always be included
- what should be included only when present
- what should be excluded
- which fixed material should be collected alongside the Target

without relying on shell history, conversation history, or human memory.

Use `--preview` to inspect what would be selected from the current filesystem before writing an Archive.

When Configurations need to be shared across related uses, one Configuration can also reuse another as its base. See [docs/CONFIGURATION.md](docs/CONFIGURATION.md) for authoring guidance and [docs/SPECIFICATION.md](docs/SPECIFICATION.md) for exact composition and resolution rules.

## Before sharing an Archive

`dirpluck` does not infer which files contain sensitive information.

Before creating an Archive that will leave the local environment, use `--preview` to review its contents and explicitly exclude anything that should not be included.

For example, `.env` files, private keys, credentials, and project-specific sensitive files may use different names and locations in different projects.

See [docs/TRUST.md](docs/TRUST.md) for the trust boundary around Configurations and filesystem operations, including absolute paths, overwrite behavior, and Archives intended to leave the local environment.

## A small example

When `--config` is omitted, `dirpluck` uses `default.dirpluck` from the current working directory. Starting with this default Configuration is the simplest way to begin.

Save the following as `default.dirpluck`:

```toml
[about]
description = "Review package for the example project."

[pluck]
description = "Project files selected for review."
must = ["README.md", "src", "tests"]
ignore = [".git/", "__pycache__/", "*.pyc"]

[always.guidelines]
path = "review-guidelines"
description = "Review guidelines shared across projects."
must = ["*.md"]

[output]
path = "review.zip"
```

Suppose the same directory contains these files:

```text
.
├── default.dirpluck
├── example/
│   ├── README.md
│   ├── src/
│   │   └── main.py
│   └── tests/
│       └── test_main.py
└── review-guidelines/
    └── review.md
```

First, use `--preview` to inspect what would go into the Archive:

```console
dirpluck example --preview
```

For this example, the preview is:

```text
├── README.md
├── example/
│   ├── README.md
│   ├── src/
│   │   └── main.py
│   └── tests/
│       └── test_main.py
└── review-guidelines/
    └── review.md
```

The leading `README.md` is generated by `dirpluck` to describe the Archive contents.

If the preview looks right, build the Archive with the same Target:

```console
dirpluck example
```

The `[output]` declaration creates `review.zip`. It contains the files shown by the preview together with the generated `README.md`.

For this example, the generated `README.md` is:

```markdown
# Archive contents

Review package for the example project.

## `example/`

Files: 3

Project files selected for review.

## `review-guidelines/`

Files: 1

Review guidelines shared across projects.
```

Descriptions written in the Configuration are used as human-facing context in this Archive README:

- `[about].description` describes the Archive as a whole.
- `[pluck].description` describes the source collected from the Target.
- `[always.guidelines].description` describes the fixed `review-guidelines/` source.

These `description` values are optional. Omitting a source description does not change extraction semantics.

This lets a Configuration record not only what to collect, but also enough context to explain what the resulting Archive is for when that context is useful.

This example selects a Target from the default Scope and places it directly at the Archive root. In larger setups, additional Scopes can separate the filesystem ranges from which Targets are selected, and a Namespace can organize sources under an explicit path inside the Archive.

When the same combination of Configuration, Target, and Case is used repeatedly, an Invocation Template can store the call. A single Invocation Template can contain multiple named Invocations, so calls for purposes such as review, docs, and release can be kept in one file.

See [docs/CONFIGURATION.md](docs/CONFIGURATION.md) for Configuration fields, Scope, Case, Always, Output, Namespace, and related authoring details. See [docs/CLI.md](docs/CLI.md) for CLI options, Configuration selection, and Invocation Templates.

## Installation

The current version is **0.9.0**.

Python 3.11 or later is required.

```console
pip install dirpluck
dirpluck --version
```

`dirpluck` has no third-party runtime dependencies.

## Documentation

The documentation is separated by purpose:

- [GLOSSARY.md](GLOSSARY.md): meanings of the concepts used throughout the documentation.
- [docs/CONFIGURATION.md](docs/CONFIGURATION.md): a guide for writing `.dirpluck` Configurations.
- [docs/CLI.md](docs/CLI.md): a guide to the CLI and `.dirpluck-inv` Invocation Templates.
- [docs/PYTHON_API.md](docs/PYTHON_API.md): the small official Python API for using the same execution model as the CLI.
- [docs/SPECIFICATION.md](docs/SPECIFICATION.md): exact rules for Configuration composition, resolution, matching, filesystem traversal, Archives, Output, and validation.
- [docs/TRUST.md](docs/TRUST.md): the trust boundary for Configurations and filesystem operations, and what users are responsible for reviewing.
- [CHANGELOG.md](CHANGELOG.md): release history.

## License

`dirpluck` is released under the MIT License.

See [LICENSE](LICENSE) for details.
