docker-devtools 0.0.1__tar.gz

docker_devtools-0.0.1/.gitignore

@@ -0,0 +1,40 @@
+# Go
+/build/
+*.test
+
+# Python
+__pycache__/
+*.py[cod]
+.venv/
+venv/
+dist/
+build/
+*.egg-info/
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.coverage
+.coverage.*
+coverage.xml
+htmlcov/
+
+# hatch-vcs writes this at build time
+_version.py
+
+# uv
+uv.lock
+requirements.txt
+
+# vale style packs are fetched by `vale sync`
+.vale-styles/
+.vale-commits/styles/
+.vale-commits/msg.md
+
+.DS_Store
+
+# The fixture contexts are the data under test. They deliberately contain
+# directories the rules above ignore (__pycache__, build/), because ignoring
+# those is exactly the behaviour being checked. Re-include everything under
+# testdata; the negation has to name the directories too, since git will not
+# descend into an excluded one.
+!/testdata/**

docker_devtools-0.0.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Flavio Amurrio
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

docker_devtools-0.0.1/PKG-INFO

@@ -0,0 +1,227 @@
+Metadata-Version: 2.5
+Name: docker-devtools
+Version: 0.0.1
+Summary: Work on the Dockerfiles, Compose files and build context in a repository.
+Project-URL: Documentation, https://github.com/FlavioAmurrioCS/docker-devtools#readme
+Project-URL: Issues, https://github.com/FlavioAmurrioCS/docker-devtools/issues
+Project-URL: Source, https://github.com/FlavioAmurrioCS/docker-devtools
+Author-email: Flavio Amurrio <25621374+FlavioAmurrioCS@users.noreply.github.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: build-context,buildkit,docker,docker-compose,dockerfile,dockerignore,pre-commit
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Go
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3.10
+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: Programming Language :: Python :: Implementation :: CPython
+Classifier: Programming Language :: Python :: Implementation :: PyPy
+Classifier: Topic :: Software Development :: Build Tools
+Classifier: Topic :: Utilities
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# docker-devtools
+
+Work on the Docker files in a repository: the build context a Dockerfile would
+send, and the image references it and your Compose files point at.
+
+```console
+$ docker-devtools image ls
+Dockerfile:1        python:3.11-slim
+compose.yaml:3      nginx:1.25-alpine
+
+$ docker-devtools image update --tag-policy same-pattern --dry-run
+Dockerfile:1     python:3.11-slim -> python:3.14-slim      (tag 3.11-slim -> 3.14-slim)
+compose.yaml:3   nginx:1.25-alpine -> nginx:1.31-alpine    (tag 1.25-alpine -> 1.31-alpine)
+```
+
+## Why another one
+
+Renovate and Dependabot already update image references, and they do it well.
+They run as bots against a repository and open pull requests. This one runs on
+your machine and edits the files in place. It is fast enough for a pre-commit
+hook, so a stale base image gets caught before it is ever committed.
+
+Where the semantics are Docker's, this defers to Docker's own code:
+
+| Step | Package |
+| --- | --- |
+| Parse Dockerfiles | `moby/buildkit/frontend/dockerfile/parser` and `instructions` |
+| Parse image references | `google/go-containerregistry/pkg/name` |
+| Talk to registries | `google/go-containerregistry/pkg/v1/remote` |
+| Match .dockerignore rules | `moby/patternmatcher` |
+| Walk a build context | `tonistiigi/fsutil`, the package BuildKit sends contexts with |
+
+None of the `.dockerignore` semantics are reimplemented here, and CI checks
+that rather than asserting it: for every fixture, `scripts/conformance.sh`
+builds `FROM scratch` with `COPY . /`, exports the image as a tarball, and
+diffs the tar members against what `context ls` reports.
+
+## Install
+
+```console
+$ uvx docker-devtools image ls          # no install
+$ pipx run docker-devtools image ls     # no install
+$ uv tool install docker-devtools
+$ pip install docker-devtools
+$ mise use ubi:FlavioAmurrioCS/docker-devtools
+```
+
+Prebuilt binaries are attached to each
+[release](https://github.com/FlavioAmurrioCS/docker-devtools/releases). With a
+Go toolchain:
+
+```console
+$ go install github.com/FlavioAmurrioCS/docker-devtools/cmd/docker-devtools@latest
+```
+
+Reading and updating files doesn't require a Docker installation or a running
+daemon.
+Registry lookups authenticate with the same `~/.docker/config.json` the docker
+CLI uses.
+
+## Usage
+
+```text
+docker-devtools context ls [PATH]        list the files Docker would send
+docker-devtools context explain PATH     show which .dockerignore rule decided a path
+docker-devtools image ls [PATH...]       list every image reference, with file and line
+docker-devtools image update [PATH...]   rewrite references in place
+docker-devtools install-docker-plugin    register as "docker devtools"
+```
+
+### Updating image references
+
+What changes is split by how much judgement it needs.
+
+`--pin-digest` resolves the current tag to a digest and appends it, turning
+`nginx:1.29` into `nginx:1.29@sha256:…`. It doesn't decide anything about versions, so it is
+reversible and safe to run anywhere.
+
+`--tag-policy` moves the tag. The default, `same-pattern`, moves only the last
+component and keeps the suffix, so how specific your tag is decides how far it
+may move:
+
+| Current tag | same-pattern | minor | patch | latest |
+| --- | --- | --- | --- | --- |
+| `3.12-slim` | `3.13-slim` | `3.13-slim` | no change | `4.0-slim` |
+| `3.12.1-slim` | `3.12.7-slim` | `3.13.0-slim` | `3.12.7-slim` | `4.0-slim` |
+| `latest` | no change | no change | no change | no change |
+
+No policy ever changes the suffix: `-alpine` and `-slim` are different images,
+and swapping them would change your base distribution without saying so. Tags
+with no version, such as `latest` or `bookworm`, are never moved, because there
+is no ordering to move along.
+
+Add `--dry-run` to see the plan without writing, and `--fail-on-diff` to exit
+non-zero when anything would change, which is what makes it useful in CI.
+
+### What it will not touch
+
+Some references cannot be resolved to an image, and those are reported rather
+than guessed at. Pass `--unresolved` to `image ls` to see them:
+
+- `FROM builder`, where `builder` is an earlier stage
+- `COPY --from=0`, which indexes a stage
+- `FROM $BASE`, which depends on a build argument
+- `FROM scratch`, which is the empty base rather than a registry image
+- Compose values built from variables, such as `${REGISTRY}/app:latest`
+
+### Editing in place
+
+An update splices the new reference into the exact byte range the parser
+reported. It never re-encodes the file, so comments, quoting style, anchors and
+whitespace all survive:
+
+```yaml
+    image: "nginx:1.29-alpine"   # keep this comment and the quotes
+```
+
+becomes
+
+```yaml
+    image: "nginx:1.31-alpine"   # keep this comment and the quotes
+```
+
+If a byte range no longer holds the text the parse said it held, the update
+fails instead of writing. A rewrite that has drifted from the parse is a bug,
+and corrupting the file would hide it.
+
+## Shell completion
+
+The binary emits a [usage](https://usage.jdx.dev) spec describing its own
+command tree, and the `usage` CLI turns that into completions for bash, zsh,
+fish, powershell and nushell:
+
+```console
+$ mise use usage
+$ usage g completion zsh docker-devtools --usage-cmd 'docker-devtools --usage-spec' --install
+```
+
+The generated scripts call back to `usage` at completion time, so it has to stay
+on your PATH. `mise run completions` regenerates all five, plus a markdown
+reference, into `build/`.
+
+## As a Docker CLI plugin
+
+```console
+$ docker-devtools install-docker-plugin
+$ docker devtools image ls
+```
+
+This symlinks the binary into `~/.docker/cli-plugins/`. Use `--system` to
+install it for every user.
+
+The subcommand is `devtools` because Docker validates plugin names against
+`^[a-z][a-z0-9]*$` and refuses to load anything else. Python wheels cannot do
+this step at install time: they have no post-install hook, and
+`~/.docker/cli-plugins/` sits outside every Python install path.
+
+## Python API
+
+The wheel bundles the binary and a typed wrapper.
+
+```python
+from docker_devtools import image_ls
+from docker_devtools import image_update
+
+for ref in image_ls(".").resolved():
+    print(f"{ref.path}:{ref.line}", ref.repository, ref.tag)
+
+report = image_update(".", pin_digest=True, dry_run=True)
+for change in report.changes:
+    print(change.old, "->", change.new, f"({change.reason})")
+```
+
+`image_update` defaults to `dry_run=True`, so calling it by accident cannot
+rewrite a repository.
+
+## Development
+
+`mise.toml` defines the tools and the tasks.
+
+```console
+$ mise run build         # compile into ./build
+$ mise run test          # go test + pytest
+$ mise run lint          # pre-commit across the repo
+$ mise run conformance   # diff context listing against real docker build
+$ mise run completions   # regenerate completions and docs
+$ mise run wheels        # every platform wheel into ./dist
+$ mise run test-clone    # verify a fresh clone in a container
+```
+
+Registry behaviour is tested against `go-containerregistry`'s in-process
+registry, so the suite doesn't touch the network or carry recorded fixtures.
+
+## License
+
+MIT. See [LICENSE](LICENSE).
+
+`src/docker_devtools/_find.py` adapts the binary-discovery search order from
+[uv](https://github.com/astral-sh/uv), which is MIT OR Apache-2.0.

docker_devtools-0.0.1/README.md

@@ -0,0 +1,199 @@
+# docker-devtools
+
+Work on the Docker files in a repository: the build context a Dockerfile would
+send, and the image references it and your Compose files point at.
+
+```console
+$ docker-devtools image ls
+Dockerfile:1        python:3.11-slim
+compose.yaml:3      nginx:1.25-alpine
+
+$ docker-devtools image update --tag-policy same-pattern --dry-run
+Dockerfile:1     python:3.11-slim -> python:3.14-slim      (tag 3.11-slim -> 3.14-slim)
+compose.yaml:3   nginx:1.25-alpine -> nginx:1.31-alpine    (tag 1.25-alpine -> 1.31-alpine)
+```
+
+## Why another one
+
+Renovate and Dependabot already update image references, and they do it well.
+They run as bots against a repository and open pull requests. This one runs on
+your machine and edits the files in place. It is fast enough for a pre-commit
+hook, so a stale base image gets caught before it is ever committed.
+
+Where the semantics are Docker's, this defers to Docker's own code:
+
+| Step | Package |
+| --- | --- |
+| Parse Dockerfiles | `moby/buildkit/frontend/dockerfile/parser` and `instructions` |
+| Parse image references | `google/go-containerregistry/pkg/name` |
+| Talk to registries | `google/go-containerregistry/pkg/v1/remote` |
+| Match .dockerignore rules | `moby/patternmatcher` |
+| Walk a build context | `tonistiigi/fsutil`, the package BuildKit sends contexts with |
+
+None of the `.dockerignore` semantics are reimplemented here, and CI checks
+that rather than asserting it: for every fixture, `scripts/conformance.sh`
+builds `FROM scratch` with `COPY . /`, exports the image as a tarball, and
+diffs the tar members against what `context ls` reports.
+
+## Install
+
+```console
+$ uvx docker-devtools image ls          # no install
+$ pipx run docker-devtools image ls     # no install
+$ uv tool install docker-devtools
+$ pip install docker-devtools
+$ mise use ubi:FlavioAmurrioCS/docker-devtools
+```
+
+Prebuilt binaries are attached to each
+[release](https://github.com/FlavioAmurrioCS/docker-devtools/releases). With a
+Go toolchain:
+
+```console
+$ go install github.com/FlavioAmurrioCS/docker-devtools/cmd/docker-devtools@latest
+```
+
+Reading and updating files doesn't require a Docker installation or a running
+daemon.
+Registry lookups authenticate with the same `~/.docker/config.json` the docker
+CLI uses.
+
+## Usage
+
+```text
+docker-devtools context ls [PATH]        list the files Docker would send
+docker-devtools context explain PATH     show which .dockerignore rule decided a path
+docker-devtools image ls [PATH...]       list every image reference, with file and line
+docker-devtools image update [PATH...]   rewrite references in place
+docker-devtools install-docker-plugin    register as "docker devtools"
+```
+
+### Updating image references
+
+What changes is split by how much judgement it needs.
+
+`--pin-digest` resolves the current tag to a digest and appends it, turning
+`nginx:1.29` into `nginx:1.29@sha256:…`. It doesn't decide anything about versions, so it is
+reversible and safe to run anywhere.
+
+`--tag-policy` moves the tag. The default, `same-pattern`, moves only the last
+component and keeps the suffix, so how specific your tag is decides how far it
+may move:
+
+| Current tag | same-pattern | minor | patch | latest |
+| --- | --- | --- | --- | --- |
+| `3.12-slim` | `3.13-slim` | `3.13-slim` | no change | `4.0-slim` |
+| `3.12.1-slim` | `3.12.7-slim` | `3.13.0-slim` | `3.12.7-slim` | `4.0-slim` |
+| `latest` | no change | no change | no change | no change |
+
+No policy ever changes the suffix: `-alpine` and `-slim` are different images,
+and swapping them would change your base distribution without saying so. Tags
+with no version, such as `latest` or `bookworm`, are never moved, because there
+is no ordering to move along.
+
+Add `--dry-run` to see the plan without writing, and `--fail-on-diff` to exit
+non-zero when anything would change, which is what makes it useful in CI.
+
+### What it will not touch
+
+Some references cannot be resolved to an image, and those are reported rather
+than guessed at. Pass `--unresolved` to `image ls` to see them:
+
+- `FROM builder`, where `builder` is an earlier stage
+- `COPY --from=0`, which indexes a stage
+- `FROM $BASE`, which depends on a build argument
+- `FROM scratch`, which is the empty base rather than a registry image
+- Compose values built from variables, such as `${REGISTRY}/app:latest`
+
+### Editing in place
+
+An update splices the new reference into the exact byte range the parser
+reported. It never re-encodes the file, so comments, quoting style, anchors and
+whitespace all survive:
+
+```yaml
+    image: "nginx:1.29-alpine"   # keep this comment and the quotes
+```
+
+becomes
+
+```yaml
+    image: "nginx:1.31-alpine"   # keep this comment and the quotes
+```
+
+If a byte range no longer holds the text the parse said it held, the update
+fails instead of writing. A rewrite that has drifted from the parse is a bug,
+and corrupting the file would hide it.
+
+## Shell completion
+
+The binary emits a [usage](https://usage.jdx.dev) spec describing its own
+command tree, and the `usage` CLI turns that into completions for bash, zsh,
+fish, powershell and nushell:
+
+```console
+$ mise use usage
+$ usage g completion zsh docker-devtools --usage-cmd 'docker-devtools --usage-spec' --install
+```
+
+The generated scripts call back to `usage` at completion time, so it has to stay
+on your PATH. `mise run completions` regenerates all five, plus a markdown
+reference, into `build/`.
+
+## As a Docker CLI plugin
+
+```console
+$ docker-devtools install-docker-plugin
+$ docker devtools image ls
+```
+
+This symlinks the binary into `~/.docker/cli-plugins/`. Use `--system` to
+install it for every user.
+
+The subcommand is `devtools` because Docker validates plugin names against
+`^[a-z][a-z0-9]*$` and refuses to load anything else. Python wheels cannot do
+this step at install time: they have no post-install hook, and
+`~/.docker/cli-plugins/` sits outside every Python install path.
+
+## Python API
+
+The wheel bundles the binary and a typed wrapper.
+
+```python
+from docker_devtools import image_ls
+from docker_devtools import image_update
+
+for ref in image_ls(".").resolved():
+    print(f"{ref.path}:{ref.line}", ref.repository, ref.tag)
+
+report = image_update(".", pin_digest=True, dry_run=True)
+for change in report.changes:
+    print(change.old, "->", change.new, f"({change.reason})")
+```
+
+`image_update` defaults to `dry_run=True`, so calling it by accident cannot
+rewrite a repository.
+
+## Development
+
+`mise.toml` defines the tools and the tasks.
+
+```console
+$ mise run build         # compile into ./build
+$ mise run test          # go test + pytest
+$ mise run lint          # pre-commit across the repo
+$ mise run conformance   # diff context listing against real docker build
+$ mise run completions   # regenerate completions and docs
+$ mise run wheels        # every platform wheel into ./dist
+$ mise run test-clone    # verify a fresh clone in a container
+```
+
+Registry behaviour is tested against `go-containerregistry`'s in-process
+registry, so the suite doesn't touch the network or carry recorded fixtures.
+
+## License
+
+MIT. See [LICENSE](LICENSE).
+
+`src/docker_devtools/_find.py` adapts the binary-discovery search order from
+[uv](https://github.com/astral-sh/uv), which is MIT OR Apache-2.0.

docker_devtools-0.0.1/cmd/docker-devtools/context.go

@@ -0,0 +1,166 @@
+package main
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"io"
+	"strings"
+
+	"github.com/FlavioAmurrioCS/docker-devtools/dctx"
+)
+
+// ContextCmd groups the build-context commands. The listing itself is in the
+// dctx package, whose output scripts/conformance.sh diffs against a real
+// docker build for every fixture.
+type ContextCmd struct {
+	Ls      ContextLsCmd      `cmd:"" help:"List the files Docker sends as the build context."`
+	Explain ContextExplainCmd `cmd:"" help:"Show which .dockerignore rule decided a path."`
+}
+
+type ContextLsCmd struct {
+	Path string `arg:"" optional:"" default:"." help:"Build context directory." type:"path"`
+
+	File    string `short:"f" placeholder:"NAME" help:"Dockerfile name, which also selects <name>.dockerignore."`
+	Ignored bool   `xor:"mode" help:"List the excluded files instead of the included ones."`
+	All     bool   `xor:"mode" help:"List every file, prefixed + for sent and - for excluded."`
+	Size    bool   `help:"Prefix each path with its size in bytes."`
+	Summary bool   `help:"Print totals to stderr after the listing."`
+	JSON    bool   `name:"json" help:"Emit the full result as JSON."`
+	Zero    bool   `short:"0" help:"Separate paths with NUL, for xargs -0."`
+}
+
+func (c *ContextLsCmd) Run(st *Streams) error {
+	mode := dctx.ModeIncluded
+	switch {
+	case c.All:
+		mode = dctx.ModeAll
+	case c.Ignored:
+		mode = dctx.ModeIgnored
+	}
+
+	res, err := dctx.Walk(context.Background(), dctx.Options{
+		Context:    c.Path,
+		Dockerfile: c.File,
+		Mode:       mode,
+	})
+	if err != nil {
+		return err
+	}
+	for _, w := range res.Warnings {
+		fmt.Fprintln(st.Stderr, "warning:", w)
+	}
+	if c.JSON {
+		return writeJSON(st.Stdout, res)
+	}
+
+	sep := "\n"
+	if c.Zero {
+		sep = "\x00"
+	}
+	for _, e := range res.Entries {
+		var b strings.Builder
+		if c.All {
+			if e.Status == dctx.StatusIncluded {
+				b.WriteString("+ ")
+			} else {
+				b.WriteString("- ")
+			}
+		}
+		if c.Size {
+			fmt.Fprintf(&b, "%10d  ", e.Size)
+		}
+		b.WriteString(e.Path)
+		b.WriteString(sep)
+		if _, err := stringWrite(st.Stdout, b.String()); err != nil {
+			return err
+		}
+	}
+	if c.Summary {
+		printSummary(st.Stderr, res)
+	}
+	return nil
+}
+
+type ContextExplainCmd struct {
+	Path string `arg:"" help:"Path to explain, relative to the context or absolute. It need not exist."`
+
+	Dir  string `short:"C" default:"." placeholder:"DIR" help:"Build context directory." type:"path"`
+	File string `short:"f" placeholder:"NAME" help:"Dockerfile name, which also selects <name>.dockerignore."`
+	JSON bool   `name:"json" help:"Emit the explanation as JSON."`
+}
+
+func (c *ContextExplainCmd) Run(st *Streams) error {
+	exp, err := dctx.Explain(dctx.Options{Context: c.Dir, Dockerfile: c.File}, c.Path)
+	if err != nil {
+		return err
+	}
+	if c.JSON {
+		return writeJSON(st.Stdout, exp)
+	}
+
+	fmt.Fprintf(st.Stdout, "%s: %s\n", exp.Path, exp.Status)
+	if !exp.Exists {
+		fmt.Fprintln(st.Stdout, "  (path does not exist in the context)")
+	}
+	label := exp.Ignorefile
+	if label == "" {
+		label = "(no ignore file)"
+	}
+	if len(exp.Rules) == 0 {
+		fmt.Fprintf(st.Stdout, "  no rule in %s matches; included by default\n", label)
+		return nil
+	}
+	for _, r := range exp.Rules {
+		effect := "ignored"
+		if r.Negated {
+			effect = "re-included"
+		}
+		line := fmt.Sprintf("  %s:%d", label, r.Line)
+		fmt.Fprintf(st.Stdout, "%-24s %-24s %s", line, r.Rule, effect)
+		if r.Decisive {
+			fmt.Fprint(st.Stdout, "  (decisive)")
+		}
+		fmt.Fprintln(st.Stdout)
+	}
+	return nil
+}
+
+func printSummary(w io.Writer, res *dctx.Result) {
+	fmt.Fprintf(w, "included: %s, %s\n",
+		plural(res.Summary.Included.Files, "file"), humanBytes(res.Summary.Included.Bytes))
+	if res.Summary.Ignored != nil {
+		fmt.Fprintf(w, "ignored:  %s, %s\n",
+			plural(res.Summary.Ignored.Files, "file"), humanBytes(res.Summary.Ignored.Bytes))
+	} else {
+		fmt.Fprintln(w, "ignored:  not counted (ignored directories were skipped; use --all)")
+	}
+}
+
+func plural(n int64, noun string) string {
+	if n == 1 {
+		return fmt.Sprintf("%d %s", n, noun)
+	}
+	return fmt.Sprintf("%d %ss", n, noun)
+}
+
+func humanBytes(n int64) string {
+	const unit = 1024
+	if n < unit {
+		return fmt.Sprintf("%d B", n)
+	}
+	div, exp := int64(unit), 0
+	for v := n / unit; v >= unit; v /= unit {
+		div *= unit
+		exp++
+	}
+	return fmt.Sprintf("%.1f %ciB", float64(n)/float64(div), "KMGTPE"[exp])
+}
+
+func writeJSON(w io.Writer, v any) error {
+	enc := json.NewEncoder(w)
+	enc.SetIndent("", "  ")
+	return enc.Encode(v)
+}
+
+func stringWrite(w io.Writer, s string) (int, error) { return io.WriteString(w, s) }