Metadata-Version: 2.4
Name: dirpluck
Version: 0.6.2
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 :: 3 - Alpha
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 CLI tool for recording a recurring decision, "which files belong together?", in TOML and building a ZIP archive from the same declared intent later.

Rather than copying everything around a workspace like a backup, it is intended to package only the material needed for an explicit purpose such as review, handoff, research, recurring work, or a working context shared with an LLM.

## Where it fits

### Gather fixed material from several locations

When files for one purpose live in different directories, they can be fixed in a Configuration as Companions. A Companion source directory does not need to live near the Configuration and may directly reference another filesystem location.

For example, a review package can combine proposal material, research results, and legal references, or a recurring workflow can gather the same kinds of material each time. A Configuration may consist entirely of Companions when nothing needs to vary at runtime.

### Attach stable references to a changing subject

Use a Target when the same selection rules should be applied to different projects, submissions, cases, or similar subjects. The Target selection stays in the Configuration while the concrete source directory is supplied when `dirpluck` runs.

Stable guidelines, templates, and reference material can remain as Companions in the same archive. This keeps the extraction intent fixed while only the subject changes.

### Reuse an extraction intent declared elsewhere

When a related project already has a Configuration, a Configuration import can use it as an inner layer instead of copying the same definitions into the parent Configuration.

Exact import ordering, shadowing, and filesystem-boundary rules live in [docs/SPECIFICATION.md](docs/SPECIFICATION.md). For the authoring forms needed to write a Configuration, see [docs/CONFIGURATION.md](docs/CONFIGURATION.md).

## Why keep the intent as a declaration

For a one-off archive, creating a ZIP by hand may be simpler. `dirpluck` is useful when the same kind of judgment needs to be made again.

A Configuration records what is required, what is optional, what should be excluded, and which fixed references belong with the package. That intent does not have to be reconstructed from shell history, conversation history, or memory. `--dry-run` can show how the current filesystem resolves before anything is written.

For LLM-assisted work, `dirpluck` prepares the material on the local filesystem as an Archive. That Archive can be uploaded to a non-local conversational LLM or placed into the workspace used by a local agent. This workflow does not assume that the LLM operates `dirpluck` itself.

## Configuration and filesystem trust

When creating an Archive that will leave the local environment, review the selection before creating it. `dirpluck` does not infer which files are sensitive; explicitly exclude material that should not be collected. For example:

```toml
exclude = [".git/", ".env*", "*.pem", "*.key"]
```

This is only an example; project-specific sensitive material may use different names or locations. See [docs/TRUST.md](docs/TRUST.md) for how to treat Configurations, absolute paths, overwrite behavior, and Archives that will leave the local environment.

## A small example

The following Configuration combines a runtime Target with fixed review guidelines:

```toml
[target]
description = "The project currently under review."
include_if_exists = ["README.md", "src", "tests"]
exclude = [".git/", "__pycache__/", "*.pyc"]
if_empty = "allow"

[companion.guidelines]
path = "review-guidelines"
description = "Guidelines used for every review."
include = ["*.md"]

[output]
path = "artifacts/review.zip"
if_exists = "overwrite"
```

```console
dirpluck projects/example --dry-run
dirpluck projects/example
```

For all Configuration fields and a larger example, see [docs/CONFIGURATION.md](docs/CONFIGURATION.md). For CLI options and Configuration discovery, see [docs/CLI.md](docs/CLI.md).

## Installation

Python 3.11 or later is required. The current release is `0.6.2`.

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

`dirpluck` has no third-party runtime dependencies.

## Documentation

The documents are separated by reading purpose:

- [GLOSSARY.md](GLOSSARY.md): the concepts used throughout the documentation.
- [docs/CONFIGURATION.md](docs/CONFIGURATION.md): how to write TOML Configurations.
- [docs/CLI.md](docs/CLI.md): how to operate the CLI.
- [docs/SPECIFICATION.md](docs/SPECIFICATION.md): exact rules for resolution, matching, filesystem boundaries, archives, output, and validation.
- [docs/TRUST.md](docs/TRUST.md): the trust boundary for Configurations and filesystem operations.
- [CHANGELOG.md](CHANGELOG.md): release history.

The wheel includes compact `dirpluck/docs/CONFIGURATION.md` and `dirpluck/docs/CLI.md` references together with `dirpluck/docs/TRUST.md`, so the trust model remains available in an installed package. For more detail, use the documentation in the source distribution or repository.

## Public interface

The compatibility-supported public surface is the `dirpluck` CLI and the TOML Configuration format. Python modules inside the package are internal implementation unless explicitly documented as a public API.
