Metadata-Version: 2.4
Name: clean-to-execute
Version: 0.0.1
Summary: Safely clean the Docker Compose resources for a local GitHub repository.
Author: Kaizten Analytics
License-Expression: LicenseRef-Proprietary
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Requires-Python: >=3.10
Description-Content-Type: text/markdown

# Clean to Execute

`clean-to-execute` removes Docker Compose resources for a local clone of a
GitHub repository.

The repository is found recursively by inspecting Git remotes under the user's
home directory. Directory names alone are not trusted. Docker Compose files
must be at the repository root.

## Requirements

- Python 3.10 or newer
- Git
- Docker with the Compose plugin
- Access to a running Docker daemon

## Installation

From this directory:

```bash
python3 -m pip install .
```

## Usage

Execute cleanup:

```bash
clean-to-execute --organization kaizten --repository example
```

Preview cleanup without changing Docker resources:

```bash
clean-to-execute --organization kaizten --repository example --dry-run
```

Search somewhere other than `~`:

```bash
clean-to-execute \
  --organization kaizten \
  --repository example \
  --root /workspaces
```

Cleanup is destructive by default. Use `--dry-run` when only a preview is
required.

## Cleanup scope

The command recognizes `compose.yaml`, `compose.yml`, `docker-compose.yaml`,
and `docker-compose.yml` at the repository root. Docker Compose renders the
effective configuration, including its normal override and environment
interpolation behavior. All Compose profiles are activated for inspection and
shutdown, so services and ports behind profiles are included without requiring
the caller to name each profile.

By default, the command:

1. Stops and removes the entire Compose project, including orphan containers,
   so all of its published ports are released.
2. Deletes the project's non-external named and anonymous volumes.
3. Deletes all other dangling Docker volumes, while preserving external
   volumes declared by this Compose project.
4. Force-removes local images referenced by the Compose configuration whose
   namespace matches the GitHub organization.

The namespace comparison works across registries. For example, all of these
belong to the GitHub organization `kaizten`:

- `kaizten/api`
- `docker.io/kaizten/api`
- `ghcr.io/kaizten/api`
- `registry.example.com/kaizten/api`

Containers outside the selected Compose project are never stopped or removed.
An external container may still prevent Docker from deleting an image; that is
reported as a cleanup failure.

If multiple local clones match the same GitHub remote, the command lists them
and exits instead of choosing one implicitly.

## Development

```bash
python3 -m unittest discover -s tests -v
./build-package.sh
```
