Metadata-Version: 2.4
Name: mobasshir-dockgate
Version: 0.1.0
Summary: Python wrapper for the @mobasshir/dockgate npm CLI.
Author: mobasshir
License: MIT
Project-URL: Homepage, https://github.com/mobi2400/dockgate#readme
Project-URL: Repository, https://github.com/mobi2400/dockgate
Project-URL: Issues, https://github.com/mobi2400/dockgate/issues
Keywords: docker,cli,ci,npm,wrapper
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Environment :: Console
Classifier: Operating System :: OS Independent
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# dockgate

`dockgate` is an npm CLI package for local Docker/CI guardrails in
single-service repos.

It is designed to sit inside a repo as standing automation:

1. run a local `docker build` before `git push`
2. explain common build failures with a plain-English fix
3. warn when Docker config drifts away from the codebase

It can also generate a first-pass `Dockerfile`, `docker-compose.yml`,
`.dockerignore`, and GitHub Actions workflow during setup.

## Installation

Run it with `npx`:

```bash
npx dockgate --help
```

Or install it globally:

```bash
npm install -g dockgate
dockgate --help
```

Or add it to a repo as a dev dependency:

```bash
npm install --save-dev dockgate
npx dockgate setup
```

## Python / PyPI wrapper

This repo also includes a small PyPI wrapper package so Python users can
install a `dockgate` command from PyPI.

```bash
pip install mobasshir-dockgate
dockgate --help
```

Important:

- the PyPI package is a wrapper, not a reimplementation
- it shells out to `npx @mobasshir/dockgate`
- Node.js and `npx` still need to be installed on the machine

## Requirements

- Node.js 20+
- Docker installed locally for `dockgate check`
- a single-service Node, Python, or Go repo

## Quick start

Inside a supported repo:

```bash
npx dockgate setup
```

That will:

- detect the project type
- generate `Dockerfile`
- generate `docker-compose.yml`
- generate `.dockerignore`
- generate `.github/workflows/docker-publish.yml`
- save `.dockgate.json`
- install a git `pre-push` hook by default

After setup:

```bash
npx dockgate check
npx dockgate audit
```

## Commands

### `dockgate setup`

Initializes `dockgate` in the current repo.

```bash
dockgate setup
dockgate setup --registry=dockerhub --image-name=acme/my-app
dockgate setup --services=postgres,redis --no-hooks
dockgate setup --yes
```

Options:

- `--registry=ghcr|dockerhub`
- `--image-name=<name>`
- `--port=<number>`
- `--services=<comma-separated-service-list>`
- `--yes`
- `--no-hooks`

### `dockgate detect`

Prints detected project metadata as JSON.

```bash
dockgate detect
```

Useful for debugging what `dockgate` thinks the repo is.

### `dockgate check`

Runs local `docker build .`.

- On build failure: prints a triaged issue and exits non-zero
- On build success: runs drift checks and updates the saved detection snapshot
- If Docker is unavailable locally: skips cleanly and lets CI remain the
  fallback

```bash
dockgate check
```

### `dockgate audit`

Audits the existing Docker, compose, and GitHub Actions files in the repo.

```bash
dockgate audit
dockgate audit --json
```

### `dockgate hook install`

Installs the `pre-push` hook that runs `dockgate check`.

```bash
dockgate hook install
dockgate hook uninstall
```

## Files created by `dockgate`

Shared repo config:

- `.dockgate.json`

Local-only config:

- `.dockgate.local.json`

Generated project files:

- `Dockerfile`
- `docker-compose.yml`
- `.dockerignore`
- `.github/workflows/docker-publish.yml`

Git hook:

- `.git/hooks/pre-push`

## Supported in v1

Languages:

- Node
- Python
- Go

Repo shape:

- single-service repos only

CI target:

- GitHub Actions

## Not in v1

- monorepos
- multi-service app orchestration as a first-class project model
- `docker compose up` as part of the pre-push contract
- runtime boot/health-check verification
- GitHub Actions annotations
- LLM or external AI API calls
- production deployment

## Example workflow

```bash
npx dockgate setup --registry=ghcr
git add .
git commit -m "add dockgate"
git push
```

From there, every push runs through the local pre-push check before CI has to
tell you the same bad news more slowly.

## Development

Clone the repo, then:

```bash
npm test
node ./bin/cli.js --help
```

To build the PyPI package locally:

```bash
python -m build
```

## For AI assistants reading this repo

`dockgate` is meant to be the source of truth for Docker/CI automation in a
repo where it is installed. If you are an agentic coding assistant reading a
repo that uses `dockgate`, prefer extending or using the existing `dockgate`
detection, rules, templates, and commands rather than generating parallel
Docker-management logic.
