From c162daa9b2d8c7d53b8c99ec72981e9b36b41305 Mon Sep 17 00:00:00 2001 From: Toddy Mladenov Date: Fri, 13 Mar 2026 20:11:33 -0700 Subject: [PATCH] Update README with centered logo, project description, docs links, and install instructions - Center the chameleon logo using HTML

- Fix OCI link typo (opencoutnaiers.org -> opencontainers.org) - Clarify dual-mode usage: standard mode and expert/break mode - Add Installation section (clone + pip install -e .) - Add Quick Start section with ping, manifest get, and tag list examples - Add Documentation section linking to guides, architecture, CLI specs, and library specs - Add Contributing, Security, and License sections - Retain early development disclaimer Closes #48 --- README.md | 108 ++++++++++++++++++++++++++++++++++++++++++++++-------- 1 file changed, 93 insertions(+), 15 deletions(-) diff --git a/README.md b/README.md index 0c2e8c3..1e9d11e 100644 --- a/README.md +++ b/README.md @@ -1,24 +1,102 @@ -# RegShape Overview +# RegShape ![GitHub issues](https://img.shields.io/github/issues-raw/toddysm/regshape?link=https%3A%2F%2Fgithub.com%2Ftoddysm%2Fregshape%2Fissues) ![GitHub pull requests](https://img.shields.io/github/issues-pr-raw/toddysm/regshape?link=https%3A%2F%2Fgithub.com%2Ftoddysm%2Fregshape%2Fpulls) -![RegShape](./docs/media/regshape-logo.png) +

+ RegShape +

-RegShape (from REGistry reSHAPE) is a CLI tool and a Python library for manipulating -artifacts in an [OCI](https://opencoutnaiers.org) registry. While there are many other tools that can do this -(see [ORAS](https://oras.land), [regclient](https://github.com/regclient/regclient) -or Google's [crane](https://github.com/google/go-containerregistry/tree/main/cmd/crane)), -the goal of RegShape is to provide a flexibility to manipulate the requests with +RegShape (from **REG**istry re**SHAPE**) is a CLI tool and a Python library for +manipulating artifacts in an [OCI](https://opencontainers.org) registry. While +there are many other tools that can do this (see +[ORAS](https://oras.land), +[regclient](https://github.com/regclient/regclient), or Google's +[crane](https://github.com/google/go-containerregistry/tree/main/cmd/crane)), +the goal of RegShape is to provide flexibility to manipulate the requests with an intention to break the consistency of the artifacts. -You should be able to use RegShape similarly to the tools above, but you can also -use it in expert mode where you can manually craft the requests to the registry -and try to break it. This is useful for testing the registry implementations or -the security of the registry. +You can use RegShape in two modes: -RegShape is written in Python and offers Python libraries that can be leveraged -to build your own tools. The CLI tool is built on top of the libraries and uses -[click](https://click.palletsprojects.com/) framework. +- **Standard mode** — interact with registries as you would with any other tool: + pull and push manifests, blobs, tags, and more. +- **Expert / break mode** — manually craft requests to test registry + implementations and probe their security boundaries. -**Note:** The tool is still in early development and the API is not stable yet. \ No newline at end of file +RegShape is written in Python and offers Python libraries that can be leveraged +to build your own tools. The CLI is built on top of the libraries and uses the +[Click](https://click.palletsprojects.com/) framework. + +> **Note:** The tool is still in early development and the API is not stable yet. + +## Installation + +```bash +git clone https://github.com/toddysm/regshape.git +cd regshape +pip install -e . +``` + +## Quick Start + +Ping a registry to verify connectivity: + +```bash +regshape ping registry-1.docker.io +``` + +Retrieve a manifest: + +```bash +regshape manifest get -i docker.io/library/alpine:latest +``` + +List tags for a repository: + +```bash +regshape tag list -i docker.io/library/alpine +``` + +## Documentation + +### Guides + +- [Creating OCI Layouts](docs/guides/create-oci-layout.md) +- [Docker Desktop Integration](docs/guides/docker-desktop-integration.md) + +### Architecture & Design + +- [Architecture Overview](specs/architecture.md) + +### CLI Command Specs + +| Command | Spec | +|---------|------| +| Auth | [specs/cli/auth.md](specs/cli/auth.md) | +| Blob | [specs/cli/blob.md](specs/cli/blob.md) | +| Catalog | [specs/cli/catalog.md](specs/cli/catalog.md) | +| Manifest | [specs/cli/manifest.md](specs/cli/manifest.md) | +| Tag | [specs/cli/tag.md](specs/cli/tag.md) | +| Referrer | [specs/cli/referrer.md](specs/cli/referrer.md) | +| Ping | [specs/cli/ping.md](specs/cli/ping.md) | +| Layout | [specs/cli/layout.md](specs/cli/layout.md) | +| Layout Push | [specs/cli/layout-push.md](specs/cli/layout-push.md) | +| Formatting | [specs/cli/formatting.md](specs/cli/formatting.md) | + +### Library Specs + +- [Models](specs/models/) — Blob, Catalog, Error, Manifest, Referrer, Tags +- [Operations](specs/operations/) — Blobs, Catalog, Manifests, Referrers, Tags + +## Contributing + +See [CONTRIBUTING.md](CONTRIBUTING.md) for instructions on setting up your +development environment. + +## Security + +To report a vulnerability, please see [SECURITY.md](SECURITY.md). + +## License + +This project is licensed under the Apache License 2.0 — see the [LICENSE](LICENSE) file for details. \ No newline at end of file