springdocker 1.0.1__tar.gz

springdocker-1.0.1/PKG-INFO

@@ -0,0 +1,189 @@
+Metadata-Version: 2.4
+Name: springdocker
+Version: 1.0.1
+Summary: CLI for Spring Boot Dockerfile and benchmark workflows (Maven/Gradle).
+Author: springdocker contributors
+License: UNLICENSED
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: tomli>=2.0; python_version < "3.11"
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-cov>=5.0; extra == "dev"
+Requires-Dist: ruff>=0.6.0; extra == "dev"
+Requires-Dist: mypy>=1.10; extra == "dev"
+
+# springdocker CLI
+
+CLI for Spring Boot Dockerfile and benchmark workflows across Maven and Gradle projects.
+
+## Install
+
+### Local editable
+
+```bash
+python3 -m pip install -e .
+```
+
+### pipx
+
+```bash
+pipx install springdocker
+springdocker --help
+```
+
+Upgrade:
+
+```bash
+pipx upgrade springdocker
+```
+
+### uv
+
+```bash
+uv tool install springdocker
+uv tool upgrade springdocker
+```
+
+## Quick usage
+
+```bash
+springdocker init --project-root samples/java-spring-docker --build-tool maven --profile quick
+springdocker doctor --project-root samples/java-spring-docker
+springdocker inspect --project-root samples/java-spring-docker --format json
+springdocker explain --project-root samples/java-spring-docker Dockerfile.generated --format json
+springdocker benchmark compare --project-root samples/java-spring-docker benchmarks/03-custom-jre-jlink/results/raw.csv --baseline-variant with-jlink-runtime --format json
+springdocker dockerfile generate --project-root samples/java-spring-docker --output Dockerfile.generated
+springdocker benchmark generate --project-root samples/java-spring-docker --java-version 25
+springdocker benchmark run --project-root samples/java-spring-docker --profile quick --runner-arg --skip-native
+springdocker benchmark analyze --project-root samples/java-spring-docker benchmarks/04-jep483-aot-cache/results/raw.csv --format table
+springdocker benchmark analyze --project-root samples/java-spring-docker benchmarks/04-jep483-aot-cache/results/raw.csv --format json --output benchmarks/04-jep483-aot-cache/results/summary.json
+springdocker benchmark analyze --project-root samples/java-spring-docker benchmarks/04-jep483-aot-cache/results/raw.csv --fail-on-success-rate-below 95
+springdocker benchmark analyze --project-root samples/java-spring-docker benchmarks/04-jep483-aot-cache/results/raw.csv --baseline benchmarks/04-jep483-aot-cache/results/baseline.json --fail-on-regression-above 20
+```
+
+## Config file (`.springdocker.toml`)
+
+All command resolvers use precedence:
+
+1. CLI flags
+2. `.springdocker.toml`
+3. defaults
+
+Example:
+
+```toml
+[project]
+build_tool = "maven"
+
+[doctor]
+build_tool = "maven"
+
+[dockerfile]
+output = "Dockerfile.generated"
+java_version = 25
+must_have_modules_file = "must-have.txt"
+legacy_scripts = false
+wizard_args = []
+
+[benchmark.generate]
+java_version = 25
+legacy_scripts = false
+
+[benchmark.run]
+profile = "quick"
+runner_args = ["--skip-native"]
+cpuset_cpus = "0-1"
+memory_limit = "2g"
+warmup_runs = 1
+max_workers = 1
+normalized_runtime = true
+legacy_scripts = false
+```
+
+When `dockerfile.must_have_modules_file` is set, springdocker reads modules from that file
+(`must-have.txt` style, one module per line, `#` comments allowed) and injects them into
+the jlink module list for reflection/dynamic-loading edge cases.
+
+Create template config:
+
+```bash
+springdocker init --project-root samples/java-spring-docker --build-tool gradle
+springdocker init --project-root samples/java-spring-docker --build-tool gradle --profile full --print
+```
+
+## Legacy compatibility mode
+
+Main command paths are internal and do not require project script files.
+
+To force script wrappers for compatibility:
+
+```bash
+springdocker dockerfile generate --use-legacy-scripts ...
+springdocker benchmark generate --use-legacy-scripts ...
+springdocker benchmark run --use-legacy-scripts ...
+```
+
+or set:
+
+```bash
+export SPRINGDOCKER_LEGACY_SCRIPTS=1
+```
+
+## Inspect command
+
+`springdocker inspect` prints static metadata about the target project:
+
+- detected build tool
+- Spring Boot version when present
+- Java version when present
+- direct dependency coordinates
+- generated Dockerfile artifacts in the project root
+- basic runtime compatibility guidance
+
+Use `--format json` for machine-readable output.
+
+## Explain command
+
+`springdocker explain` reads a springdocker-generated Dockerfile and describes the optimizations it contains:
+
+- multi-stage layout
+- BuildKit cache usage
+- jlink runtime stage
+- non-root runtime
+- tuned JVM flags
+- curated must-have modules
+
+Use `--format json` when you want stable structured output.
+
+## Security hardening
+
+See `docs/security-hardening.md` for the runtime hardening defaults and recommended `docker run` flags.
+
+## Binary distribution
+
+See `docs/distribution.md` for packaging notes and sample Homebrew, Scoop, standalone binary, and Docker runtime artifacts.
+
+## Multi-architecture builds
+
+See `docs/multiarch.md` for the Buildx-friendly Dockerfile output and example multi-arch build command.
+
+## Compare command
+
+`springdocker benchmark compare` compares each variant against a required baseline variant and reports deltas.
+
+- `--baseline-variant` selects the variant to compare against.
+- `--scenario` narrows the CSV to one scenario.
+- `--format json` produces machine-readable deltas.
+
+## Benchmark run reproducibility
+
+`springdocker benchmark run` supports deterministic benchmark controls for local or CI runs:
+
+- `--cpuset-cpus` pins benchmark containers to specific CPUs.
+- `--memory` caps container memory.
+- `--warmup-runs` executes discarded warmup probes before recording results.
+- `--max-workers` runs standard scenarios concurrently with controlled worker count.
+- `--normalized-runtime` applies read-only, no-new-privileges, and tmpfs isolation.
+
+These settings can also come from `[benchmark.run]` in `.springdocker.toml`.

springdocker-1.0.1/README.md

@@ -0,0 +1,139 @@
+# springdocker
+
+[![CI](https://github.com/mnafshin/java-spring-docker/actions/workflows/ci.yml/badge.svg)](https://github.com/mnafshin/java-spring-docker/actions/workflows/ci.yml)
+[![Release](https://github.com/mnafshin/java-spring-docker/actions/workflows/release.yml/badge.svg)](https://github.com/mnafshin/java-spring-docker/actions/workflows/release.yml)
+[![Lint](https://img.shields.io/badge/lint-ruff-blue)](https://github.com/astral-sh/ruff)
+[![Coverage](https://img.shields.io/badge/coverage-%3E%3D75%25-brightgreen)](./pyproject.toml)
+[![Benchmark](https://img.shields.io/badge/benchmark-regression--gated-orange)](./docs/benchmark-methodology.md)
+
+Developer toolkit for Spring Boot containerization and benchmark-driven JVM tuning.
+
+`springdocker` is a Python CLI that helps you inspect a Spring Boot project, generate a Dockerfile, create benchmark assets, run benchmark suites, and summarize benchmark results.
+
+## Architecture
+
+```mermaid
+flowchart LR
+  dev[Developer] --> cli[springdocker CLI]
+  cli --> cfg[.springdocker.toml]
+  cli --> proj[Spring Boot project]
+  cli --> df[Generated Dockerfile]
+  cli --> bench[Benchmark variants + raw CSV]
+  bench --> report[Table / JSON analysis]
+```
+
+See `docs/architecture.md` for the detailed module map and command lifecycle.
+
+The repo is split into three main surfaces:
+
+- `src/springdocker/` - installable CLI package and core implementation.
+- `samples/java-spring-docker/` - sample Spring Boot project used by the CLI and benchmark assets.
+- `cli/README.md` - command reference and configuration details.
+
+## What it does
+
+- Detects Maven or Gradle projects.
+- Writes a starter `.springdocker.toml` config.
+- Generates optimized Dockerfiles for the sample workflow.
+- Creates benchmark variants and runs benchmark suites.
+- Summarizes benchmark CSV output as a table or JSON.
+
+## Quick start
+
+```bash
+cd /path/to/your-repo
+python3 -m venv .venv
+. .venv/bin/activate
+python3 -m pip install -e .
+
+springdocker doctor --project-root samples/java-spring-docker
+springdocker inspect --project-root samples/java-spring-docker --format json
+springdocker explain --project-root samples/java-spring-docker Dockerfile.generated --format json
+springdocker benchmark compare --project-root samples/java-spring-docker samples/java-spring-docker/benchmarks/03-custom-jre-jlink/results/raw.csv --baseline-variant with-jlink-runtime
+springdocker init --project-root samples/java-spring-docker --build-tool maven
+springdocker dockerfile generate --project-root samples/java-spring-docker --output Dockerfile.generated
+springdocker benchmark generate --project-root samples/java-spring-docker --java-version 25
+springdocker benchmark run --project-root samples/java-spring-docker --profile quick
+springdocker benchmark analyze --project-root samples/java-spring-docker samples/java-spring-docker/benchmarks/04-custom-jre-jlink/results/raw.csv
+```
+
+## CLI workflow
+
+1. `doctor` checks the project root and build tool.
+2. `init` writes a starter config file.
+3. `dockerfile generate` writes a Dockerfile to the requested path.
+4. `benchmark generate` creates benchmark scenarios.
+5. `benchmark run` executes the benchmark runner.
+6. `benchmark analyze` turns `raw.csv` into a table or JSON summary.
+
+See `cli/README.md` for the command reference and config precedence rules.
+
+## Benchmark methodology
+
+See `docs/benchmark-methodology.md` for the benchmark model, run profiles, and summary calculations.
+
+The sample project keeps benchmark scenarios under `samples/java-spring-docker/benchmarks/`.
+Each scenario stores generated Dockerfiles and a `results/raw.csv` file so the output stays reproducible and easy to compare.
+
+Current reports focus on:
+
+- image size
+- build duration
+- startup latency
+- success rate
+
+Benchmark summaries can be rendered as:
+
+- terminal tables
+- JSON
+
+## Supported stack
+
+This repository currently targets:
+
+- Python 3.10+ for the CLI
+- Maven or Gradle Spring Boot projects
+- Spring Boot 4.0.1 sample project
+- Java 25 sample configuration
+
+## Project docs
+
+- `docs/architecture.md`
+- `docs/benchmark-methodology.md`
+- `docs/benchmark-comparison.md`
+- `docs/example-gallery.md`
+- `docs/golden-samples.md`
+- `docs/benchmark-dashboard.md`
+- `docs/extensions.md`
+- `docs/native-image-roadmap.md`
+- `docs/distribution.md`
+- `docs/compatibility-matrix.md`
+- `docs/security-hardening.md`
+- `docs/observability.md`
+- `docs/kubernetes.md`
+- `docs/adr/README.md`
+- `docs/multiarch.md`
+- `docs/onboarding.md`
+- `docs/jvm-optimization.md`
+- `ROADMAP.md`
+- `SECURITY.md`
+- `CONTRIBUTING.md`
+
+## Comparison with adjacent tools
+
+| Tool | Focus | What springdocker adds |
+|---|---|---|
+| Jib | Dockerless image build | benchmark-aware Dockerfile and runtime tuning workflows |
+| Buildpacks | Opinionated platform build | explicit Dockerfile generation and benchmark artifacts |
+| Manual Dockerfiles | Full control | project detection, config, and repeatable benchmark analysis |
+
+## Sample project docs
+
+- `samples/java-spring-docker/README.md`
+- `samples/java-spring-docker/HELP.md`
+- `samples/java-spring-docker/k8s/kustomization.yaml`
+- `samples/java-spring-docker/tools/README.md`
+
+## Contributing
+
+The main package is under `src/springdocker/`. Run `pytest`, `ruff check src tests`, and `mypy src` before pushing changes.

springdocker-1.0.1/cli/README.md

@@ -0,0 +1,174 @@
+# springdocker CLI
+
+CLI for Spring Boot Dockerfile and benchmark workflows across Maven and Gradle projects.
+
+## Install
+
+### Local editable
+
+```bash
+python3 -m pip install -e .
+```
+
+### pipx
+
+```bash
+pipx install springdocker
+springdocker --help
+```
+
+Upgrade:
+
+```bash
+pipx upgrade springdocker
+```
+
+### uv
+
+```bash
+uv tool install springdocker
+uv tool upgrade springdocker
+```
+
+## Quick usage
+
+```bash
+springdocker init --project-root samples/java-spring-docker --build-tool maven --profile quick
+springdocker doctor --project-root samples/java-spring-docker
+springdocker inspect --project-root samples/java-spring-docker --format json
+springdocker explain --project-root samples/java-spring-docker Dockerfile.generated --format json
+springdocker benchmark compare --project-root samples/java-spring-docker benchmarks/03-custom-jre-jlink/results/raw.csv --baseline-variant with-jlink-runtime --format json
+springdocker dockerfile generate --project-root samples/java-spring-docker --output Dockerfile.generated
+springdocker benchmark generate --project-root samples/java-spring-docker --java-version 25
+springdocker benchmark run --project-root samples/java-spring-docker --profile quick --runner-arg --skip-native
+springdocker benchmark analyze --project-root samples/java-spring-docker benchmarks/04-jep483-aot-cache/results/raw.csv --format table
+springdocker benchmark analyze --project-root samples/java-spring-docker benchmarks/04-jep483-aot-cache/results/raw.csv --format json --output benchmarks/04-jep483-aot-cache/results/summary.json
+springdocker benchmark analyze --project-root samples/java-spring-docker benchmarks/04-jep483-aot-cache/results/raw.csv --fail-on-success-rate-below 95
+springdocker benchmark analyze --project-root samples/java-spring-docker benchmarks/04-jep483-aot-cache/results/raw.csv --baseline benchmarks/04-jep483-aot-cache/results/baseline.json --fail-on-regression-above 20
+```
+
+## Config file (`.springdocker.toml`)
+
+All command resolvers use precedence:
+
+1. CLI flags
+2. `.springdocker.toml`
+3. defaults
+
+Example:
+
+```toml
+[project]
+build_tool = "maven"
+
+[doctor]
+build_tool = "maven"
+
+[dockerfile]
+output = "Dockerfile.generated"
+java_version = 25
+must_have_modules_file = "must-have.txt"
+legacy_scripts = false
+wizard_args = []
+
+[benchmark.generate]
+java_version = 25
+legacy_scripts = false
+
+[benchmark.run]
+profile = "quick"
+runner_args = ["--skip-native"]
+cpuset_cpus = "0-1"
+memory_limit = "2g"
+warmup_runs = 1
+max_workers = 1
+normalized_runtime = true
+legacy_scripts = false
+```
+
+When `dockerfile.must_have_modules_file` is set, springdocker reads modules from that file
+(`must-have.txt` style, one module per line, `#` comments allowed) and injects them into
+the jlink module list for reflection/dynamic-loading edge cases.
+
+Create template config:
+
+```bash
+springdocker init --project-root samples/java-spring-docker --build-tool gradle
+springdocker init --project-root samples/java-spring-docker --build-tool gradle --profile full --print
+```
+
+## Legacy compatibility mode
+
+Main command paths are internal and do not require project script files.
+
+To force script wrappers for compatibility:
+
+```bash
+springdocker dockerfile generate --use-legacy-scripts ...
+springdocker benchmark generate --use-legacy-scripts ...
+springdocker benchmark run --use-legacy-scripts ...
+```
+
+or set:
+
+```bash
+export SPRINGDOCKER_LEGACY_SCRIPTS=1
+```
+
+## Inspect command
+
+`springdocker inspect` prints static metadata about the target project:
+
+- detected build tool
+- Spring Boot version when present
+- Java version when present
+- direct dependency coordinates
+- generated Dockerfile artifacts in the project root
+- basic runtime compatibility guidance
+
+Use `--format json` for machine-readable output.
+
+## Explain command
+
+`springdocker explain` reads a springdocker-generated Dockerfile and describes the optimizations it contains:
+
+- multi-stage layout
+- BuildKit cache usage
+- jlink runtime stage
+- non-root runtime
+- tuned JVM flags
+- curated must-have modules
+
+Use `--format json` when you want stable structured output.
+
+## Security hardening
+
+See `docs/security-hardening.md` for the runtime hardening defaults and recommended `docker run` flags.
+
+## Binary distribution
+
+See `docs/distribution.md` for packaging notes and sample Homebrew, Scoop, standalone binary, and Docker runtime artifacts.
+
+## Multi-architecture builds
+
+See `docs/multiarch.md` for the Buildx-friendly Dockerfile output and example multi-arch build command.
+
+## Compare command
+
+`springdocker benchmark compare` compares each variant against a required baseline variant and reports deltas.
+
+- `--baseline-variant` selects the variant to compare against.
+- `--scenario` narrows the CSV to one scenario.
+- `--format json` produces machine-readable deltas.
+
+## Benchmark run reproducibility
+
+`springdocker benchmark run` supports deterministic benchmark controls for local or CI runs:
+
+- `--cpuset-cpus` pins benchmark containers to specific CPUs.
+- `--memory` caps container memory.
+- `--warmup-runs` executes discarded warmup probes before recording results.
+- `--max-workers` runs standard scenarios concurrently with controlled worker count.
+- `--normalized-runtime` applies read-only, no-new-privileges, and tmpfs isolation.
+
+These settings can also come from `[benchmark.run]` in `.springdocker.toml`.

springdocker-1.0.1/pyproject.toml

@@ -0,0 +1,49 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "springdocker"
+version = "1.0.1"
+description = "CLI for Spring Boot Dockerfile and benchmark workflows (Maven/Gradle)."
+readme = "cli/README.md"
+requires-python = ">=3.10"
+dependencies = [
+  "tomli>=2.0; python_version < '3.11'"
+]
+optional-dependencies = { dev = ["pytest>=8.0", "pytest-cov>=5.0", "ruff>=0.6.0", "mypy>=1.10"] }
+authors = [
+  { name = "springdocker contributors" }
+]
+license = { text = "UNLICENSED" }
+
+[project.scripts]
+springdocker = "springdocker.cli:main"
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = [".", "src"]
+addopts = "-q --cov=springdocker --cov-report=term-missing --cov-fail-under=75"
+
+[tool.ruff]
+line-length = 120
+target-version = "py310"
+src = ["src", "tests"]
+
+[tool.ruff.lint]
+select = ["F", "I"]
+
+[tool.mypy]
+python_version = "3.10"
+files = ["src"]
+pretty = true
+show_error_codes = true
+warn_unused_ignores = true
+no_implicit_optional = true
+ignore_missing_imports = true

springdocker-1.0.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

springdocker-1.0.1/src/springdocker/__init__.py

@@ -0,0 +1,9 @@
+"""springdocker CLI package."""
+
+from importlib.metadata import PackageNotFoundError, version
+
+__all__ = ["__version__"]
+try:
+    __version__ = version("springdocker")
+except PackageNotFoundError:  # pragma: no cover - local source tree fallback
+    __version__ = "0.1.0"