ros2docker 0.1.1__tar.gz

ros2docker-0.1.1/CONTRIBUTING.md

@@ -0,0 +1,207 @@
+# Contributing
+
+This is the canonical development workflow for contributors.
+
+## Development Setup
+
+Prerequisites:
+
+- Python 3.10 or 3.12 when mirroring CI.
+- Docker for runtime and E2E checks.
+- `just` for local workflow commands.
+- `pipx` for user-style installs.
+- GitHub CLI `gh` for PR and auto-merge workflows.
+
+Set up the repository from the root:
+
+```bash
+just setup
+```
+
+This creates `.venv`, installs `.[dev]`, and installs pre-commit hooks.
+
+## Local Checks
+
+Run individual checks from the repository root:
+
+```bash
+just lint
+just typecheck
+just test-unit
+just test-contract
+just docs
+just package
+```
+
+For small review PRs, run lightweight checks before opening the draft PR:
+
+```bash
+just lint
+just typecheck
+just test-unit
+```
+
+Before opening or updating a ready PR, run:
+
+```bash
+just check
+```
+
+`just check` runs linting, type checking, unit tests, contract tests, docs checks,
+and package validation. It does not run Docker E2E checks.
+
+Use Docker E2E checks when Docker/runtime behavior changed:
+
+```bash
+just test-e2e-fast
+just test-e2e-slow
+```
+
+`just test-e2e-fast` runs the fast Docker smoke fixtures. `just test-e2e-slow`
+runs the full Docker E2E suite, including slow image and ROS launch checks.
+
+## Branch And Merge Policy
+
+`main` is protected. Do not push directly to `main`.
+
+All changes must go through a pull request. Local `main` should be treated as a
+clean mirror of `origin/main`.
+
+Start each change from an up-to-date `origin/main`:
+
+```bash
+git fetch --prune
+git switch -c <type>/<short-topic> origin/main
+```
+
+Keep the change small and coherent. Update tests for changed behavior. Update
+README, docs, examples, or schema files when CLI, config, API, Docker behavior,
+or public behavior changes.
+
+After the PR has merged, clean up from a synchronized `main`:
+
+```bash
+git switch main
+git fetch --prune
+git pull --ff-only
+git branch -d <branch>
+```
+
+If local `main` diverges from `origin/main`, do not continue working on `main`.
+Move any useful local work to a topic branch first, then restore `main` to match
+`origin/main`.
+
+## Pull Request Modes
+
+This repository uses two pull request modes.
+
+### Review PRs
+
+Review PRs are the default. They are intended for small changes, documentation
+updates, and changes that should be inspected before merge.
+
+Review PRs should usually be opened as draft pull requests. Draft PRs provide
+lightweight CI feedback but are not expected to be mergeable yet.
+
+Use this flow:
+
+```bash
+gh pr create --draft --base main --title "<title>" --body "<summary>"
+```
+
+After review approval, mark the PR ready:
+
+```bash
+gh pr ready <number>
+```
+
+### Autonomous PRs
+
+Autonomous PRs are used when the user explicitly asks for autonomous iteration,
+auto-merge, or completion without further review.
+
+Autonomous PRs are opened as ready-for-review pull requests, may have auto-merge
+enabled, and must pass the full required merge gate before entering `main`.
+
+Use this flow:
+
+```bash
+gh pr create --base main --title "<title>" --body "<summary>"
+gh pr merge <number> --auto --squash --delete-branch
+gh pr checks <number> --watch --required
+```
+
+If CI fails or auto-merge is blocked, inspect the failure, fix the same PR
+branch, push the update, and repeat until the PR merges or is clearly blocked.
+
+## CI Policy
+
+The required merge gate for `main` is:
+
+```text
+ci-success
+```
+
+Draft PRs run `pr-lightweight` for quick feedback. The lightweight workflow runs:
+
+```bash
+just lint
+just typecheck
+just test-unit
+```
+
+Ready PRs and merge queue entries run `pr-merge-gate`. The `ci-success` job in
+that workflow requires:
+
+```bash
+just check
+just test-e2e-fast
+```
+
+A PR cannot merge into `main` unless `ci-success` passes. Prefer requiring only
+this stable aggregate check in branch protection so individual job names can
+change without rewriting repository policy.
+
+Full Docker E2E runs in the scheduled `nightly-e2e` workflow and may also be
+triggered manually. Nightly full E2E is not a replacement for the required PR
+merge gate.
+
+Avoid path filters or branch filters for required workflows. If a required
+workflow is skipped by filtering, GitHub can leave the check pending and block
+merging.
+
+See [docs/ci.md](docs/ci.md) for the contributor-facing CI workflow summary.
+
+## Release Workflow
+
+Releases are built from version tags. After the release PR has merged, create
+and push a tag in the form `vX.Y.Z` from the release commit:
+
+```bash
+git switch main
+git fetch --prune
+git pull --ff-only
+git tag vX.Y.Z
+git push origin vX.Y.Z
+```
+
+The `release` workflow validates the tag with non-Docker checks, package
+artifact validation, and fast Docker E2E before publishing. Successful tag
+releases publish the wheel and sdist to PyPI through Trusted Publishing, then
+create a GitHub Release with the wheel, sdist, and `SHA256SUMS`.
+
+Maintainers must configure pending Trusted Publishers on PyPI and TestPyPI for
+repository `develNor/ros2docker`, workflow `.github/workflows/release.yml`, and
+environments `pypi` and `testpypi`. No PyPI API token should be stored in GitHub
+secrets for the normal release path.
+
+Use the manual `release` workflow dispatch for TestPyPI rehearsals. Manual runs
+publish only to TestPyPI and do not create GitHub Releases.
+
+See [docs/release.md](docs/release.md) for the focused release workflow summary.
+
+## Pull Request Description
+
+Include local command results in the PR summary. Call out whether the PR is a
+review PR or an autonomous PR, which checks were run, and whether Docker/runtime
+behavior changed.

ros2docker-0.1.1/LICENSE

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2025, develNor
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

ros2docker-0.1.1/MANIFEST.in

@@ -0,0 +1,10 @@
+prune .github
+prune tests
+
+exclude .pre-commit-config.yaml
+exclude .gitignore
+exclude AGENTS.md
+exclude DEVELOPMENT_PRINCIPLES.md
+exclude justfile
+
+global-exclude __pycache__ *.py[cod] .DS_Store

ros2docker-0.1.1/PKG-INFO

@@ -0,0 +1,152 @@
+Metadata-Version: 2.4
+Name: ros2docker
+Version: 0.1.1
+Summary: Versioned CLI and Python API for building and running ROS 2 Docker workspaces.
+Author: develNor
+License-Expression: BSD-3-Clause
+Project-URL: Homepage, https://github.com/develNor/ros2docker
+Project-URL: Repository, https://github.com/develNor/ros2docker
+Project-URL: Issues, https://github.com/develNor/ros2docker/issues
+Keywords: docker,ros2,cli
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Software Development :: Build Tools
+Classifier: Topic :: System :: Installation/Setup
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == "dev"
+Requires-Dist: check-wheel-contents>=0.6; extra == "dev"
+Requires-Dist: mypy>=1.14; extra == "dev"
+Requires-Dist: pre-commit>=4.0; extra == "dev"
+Requires-Dist: pytest>=8.3; extra == "dev"
+Requires-Dist: pytest-cov>=6.0; extra == "dev"
+Requires-Dist: ruff==0.8.6; extra == "dev"
+Requires-Dist: twine>=6.0; extra == "dev"
+Dynamic: license-file
+
+# ros2docker
+
+[![pr-lightweight](https://github.com/develNor/ros2docker/actions/workflows/pr-lightweight.yml/badge.svg)](https://github.com/develNor/ros2docker/actions/workflows/pr-lightweight.yml)
+[![nightly-e2e](https://github.com/develNor/ros2docker/actions/workflows/nightly-e2e.yml/badge.svg)](https://github.com/develNor/ros2docker/actions/workflows/nightly-e2e.yml)
+
+`ros2docker` is a versioned Python CLI and API for building and running ROS 2 Docker workspaces from JSON-with-comments config files.
+
+## Install
+
+Stable release:
+
+```bash
+pipx install ros2docker
+```
+
+Latest development version:
+
+```bash
+pipx install --force git+https://github.com/develNor/ros2docker.git@main
+```
+
+Non-pipx fallback:
+
+```bash
+python3 -m pip install --user ros2docker
+```
+
+## Development Install
+
+When developing `ros2docker`, install this checkout in editable mode so the
+host `ros2docker` command imports the local source:
+
+```bash
+pipx install --force --editable /path/to/ros2docker
+```
+
+Normal Python source changes are picked up immediately by new `ros2docker`
+commands. Reinstall after changing package metadata, dependencies, or console
+entry points in `pyproject.toml`.
+
+Verify the editable command with:
+
+```bash
+ros2docker run --no-build --dry-run -m .
+```
+
+The dry run should print a `docker run` command that mounts the current
+directory as `/ws` and starts `bash`, without requiring `-f/--config`.
+
+## CLI
+
+```bash
+ros2docker run -m /host/project
+ros2docker run --no-build -m /host/project
+ros2docker build -f ros2docker.json
+ros2docker run -f ros2docker.json
+ros2docker run -f ros2docker.json --no-build -- -v /host/data:/data
+ros2docker stop -f ros2docker.json
+ros2docker exec -f ros2docker.json -- bash -lc 'ros2 --help'
+ros2docker --version
+python -m ros2docker --version
+```
+
+Every Docker action accepts `--dry-run`, which prints the Docker argv and exits without running Docker.
+The `-f`/`--config` option is optional; without it, `ros2docker` uses the default config, which starts an interactive Bash shell.
+
+## Config
+
+Config files are JSON with `//` and `/* ... */` comments. Supported keys include:
+
+```json
+{
+  "container_name": "example_ros2container",
+  "image_name": "ros2docker",
+  "run_type": "bash",
+  "mount_ws": true,
+  "enable_gui_forwarding": false,
+  "forward_ssh_agent": false,
+  "run_args": [],
+  "extra_run_args": [],
+  "build_args": {},
+  "bake_ros_packages": [],
+  "catmux_file": "/ws/catmux.yaml",
+  "catmux_params": {},
+  "command": "ros2 topic list"
+}
+```
+
+The machine-readable schema lives at `src/ros2docker/resources/schema/ros2docker.schema.json`.
+See [docs/configuration.md](docs/configuration.md) for the full configuration contract. Unknown top-level config keys are rejected.
+
+Supported `run_type` values are:
+
+- `bash`: start an interactive shell.
+- `command`: run the configured `command`.
+- `catmux`: start a catmux session from `catmux_file`.
+- `up`: start a detached keepalive container.
+
+Host paths in `-v/--volume` and bind `--mount` args expand `~` and environment variables. Relative `./` and `../` host paths are resolved from the config file directory.
+
+`bake_ros_packages` paths are also resolved from the config file directory and copied into a temporary Docker build context. The installed Python package directory is never mutated during builds.
+
+`enable_gui_forwarding` forwards the X11 socket at `/tmp/.X11-unix`.
+`forward_ssh_agent` forwards the host `SSH_AUTH_SOCK` path when the variable is set and points to an existing socket or file.
+
+## Development
+
+For contributor setup, local checks, PR modes, merge policy, and release
+workflow, see [CONTRIBUTING.md](CONTRIBUTING.md). CI behavior is summarized in
+[docs/ci.md](docs/ci.md), and release publishing is summarized in
+[docs/release.md](docs/release.md).
+
+## Python API
+
+```python
+from ros2docker.api import build, run, build_run, stop, exec_shell
+from ros2docker.config import load_config, get_config_dir
+from ros2docker.commands import make_build_command, make_run_command
+```

ros2docker-0.1.1/README.md

@@ -0,0 +1,119 @@
+# ros2docker
+
+[![pr-lightweight](https://github.com/develNor/ros2docker/actions/workflows/pr-lightweight.yml/badge.svg)](https://github.com/develNor/ros2docker/actions/workflows/pr-lightweight.yml)
+[![nightly-e2e](https://github.com/develNor/ros2docker/actions/workflows/nightly-e2e.yml/badge.svg)](https://github.com/develNor/ros2docker/actions/workflows/nightly-e2e.yml)
+
+`ros2docker` is a versioned Python CLI and API for building and running ROS 2 Docker workspaces from JSON-with-comments config files.
+
+## Install
+
+Stable release:
+
+```bash
+pipx install ros2docker
+```
+
+Latest development version:
+
+```bash
+pipx install --force git+https://github.com/develNor/ros2docker.git@main
+```
+
+Non-pipx fallback:
+
+```bash
+python3 -m pip install --user ros2docker
+```
+
+## Development Install
+
+When developing `ros2docker`, install this checkout in editable mode so the
+host `ros2docker` command imports the local source:
+
+```bash
+pipx install --force --editable /path/to/ros2docker
+```
+
+Normal Python source changes are picked up immediately by new `ros2docker`
+commands. Reinstall after changing package metadata, dependencies, or console
+entry points in `pyproject.toml`.
+
+Verify the editable command with:
+
+```bash
+ros2docker run --no-build --dry-run -m .
+```
+
+The dry run should print a `docker run` command that mounts the current
+directory as `/ws` and starts `bash`, without requiring `-f/--config`.
+
+## CLI
+
+```bash
+ros2docker run -m /host/project
+ros2docker run --no-build -m /host/project
+ros2docker build -f ros2docker.json
+ros2docker run -f ros2docker.json
+ros2docker run -f ros2docker.json --no-build -- -v /host/data:/data
+ros2docker stop -f ros2docker.json
+ros2docker exec -f ros2docker.json -- bash -lc 'ros2 --help'
+ros2docker --version
+python -m ros2docker --version
+```
+
+Every Docker action accepts `--dry-run`, which prints the Docker argv and exits without running Docker.
+The `-f`/`--config` option is optional; without it, `ros2docker` uses the default config, which starts an interactive Bash shell.
+
+## Config
+
+Config files are JSON with `//` and `/* ... */` comments. Supported keys include:
+
+```json
+{
+  "container_name": "example_ros2container",
+  "image_name": "ros2docker",
+  "run_type": "bash",
+  "mount_ws": true,
+  "enable_gui_forwarding": false,
+  "forward_ssh_agent": false,
+  "run_args": [],
+  "extra_run_args": [],
+  "build_args": {},
+  "bake_ros_packages": [],
+  "catmux_file": "/ws/catmux.yaml",
+  "catmux_params": {},
+  "command": "ros2 topic list"
+}
+```
+
+The machine-readable schema lives at `src/ros2docker/resources/schema/ros2docker.schema.json`.
+See [docs/configuration.md](docs/configuration.md) for the full configuration contract. Unknown top-level config keys are rejected.
+
+Supported `run_type` values are:
+
+- `bash`: start an interactive shell.
+- `command`: run the configured `command`.
+- `catmux`: start a catmux session from `catmux_file`.
+- `up`: start a detached keepalive container.
+
+Host paths in `-v/--volume` and bind `--mount` args expand `~` and environment variables. Relative `./` and `../` host paths are resolved from the config file directory.
+
+`bake_ros_packages` paths are also resolved from the config file directory and copied into a temporary Docker build context. The installed Python package directory is never mutated during builds.
+
+`enable_gui_forwarding` forwards the X11 socket at `/tmp/.X11-unix`.
+`forward_ssh_agent` forwards the host `SSH_AUTH_SOCK` path when the variable is set and points to an existing socket or file.
+
+## Development
+
+For contributor setup, local checks, PR modes, merge policy, and release
+workflow, see [CONTRIBUTING.md](CONTRIBUTING.md). CI behavior is summarized in
+[docs/ci.md](docs/ci.md), and release publishing is summarized in
+[docs/release.md](docs/release.md).
+
+## Python API
+
+```python
+from ros2docker.api import build, run, build_run, stop, exec_shell
+from ros2docker.config import load_config, get_config_dir
+from ros2docker.commands import make_build_command, make_run_command
+```

ros2docker-0.1.1/docs/agent-goals/documentation-audit.md

@@ -0,0 +1,33 @@
+Goal: Make public-facing documentation consistent, non-redundant, and aligned with the repository.
+
+Scope:
+
+* README
+* CONTRIBUTING
+* DEVELOPMENT / development principles
+* AGENTS.md
+* docs/
+* package metadata if it contains public-facing descriptions
+
+Document ownership:
+
+* README: user-facing purpose, installation, quick start, common usage
+* CONTRIBUTING: human contribution workflow, PR expectations, local checks
+* DEVELOPMENT: technical setup, architecture, testing, release process
+* AGENTS.md: agent-specific operating rules only; link to human docs instead of duplicating them
+
+Tasks:
+
+* Find duplicated, stale, contradictory, or misplaced information.
+* Prefer one canonical location plus links instead of repeated prose.
+* Ensure documented workflows match actual repo configuration.
+* Ensure agent instructions do not diverge from human development instructions.
+* Keep AGENTS.md short and focused on agent behavior.
+* Do not change source code unless needed to correct a documented command.
+
+Report:
+
+* final responsibility of each public-facing document
+* moved or removed duplicated content
+* remaining intentional duplication
+* any documented behavior that still lacks implementation or tests

ros2docker-0.1.1/docs/agent-goals/implementation-cleanup.md

@@ -0,0 +1,32 @@
+Goal: Improve implementation quality while preserving the current public contract.
+
+Scope:
+- source code
+- tests only where needed to preserve or clarify behavior
+- no documentation changes except small corrections caused by code cleanup
+
+Rules:
+- Do not change documented CLI/API behavior unless tests and docs prove the old behavior was stale or broken.
+- Do not remove tests.
+- Do not weaken assertions.
+- Do not add compatibility layers unless strictly required.
+- Prefer clean removal of obsolete/dead code.
+- Prefer the simplest implementation that satisfies the tests.
+- Avoid broad rewrites.
+
+Check for:
+- dead code
+- unused imports/functions/classes/constants
+- redundant branches
+- duplicated logic
+- over-abstracted helpers
+- unclear names
+- unnecessary compatibility paths
+- unnecessarily complicated control flow
+- tests that no longer test meaningful behavior
+
+After changes:
+- run formatter/linter
+- run unit tests
+- run fast e2e tests if configured
+- summarize simplifications and test coverage

ros2docker-0.1.1/docs/agent-goals/maintainer-review.md

@@ -0,0 +1,19 @@
+Review this PR as a strict maintainer.
+
+Focus:
+- scope creep
+- missing or weak tests
+- documentation drift
+- accidental public API or CLI changes
+- dead code left behind
+- unnecessary abstraction
+- CI/pre-commit mismatch
+- release or packaging risks
+
+Return:
+- blocking issues
+- non-blocking suggestions
+- files/lines for each issue
+- final recommendation: merge or request changes
+
+Do not modify files unless explicitly asked.

ros2docker-0.1.1/docs/agent-goals/quality-workflow.md

@@ -0,0 +1,19 @@
+You are executing a multi-goal repository quality workflow.
+
+Repository rules:
+- Follow AGENTS.md.
+- Use the goal templates in docs/agent-goals/.
+- Create one focused autonomous PR per goal.
+- Do not combine unrelated goals into one PR.
+- Start every goal from latest main.
+- Do not start a dependent goal until prerequisite PRs are merged.
+- If CI fails, fix the current PR instead of starting a new goal.
+- If a PR cannot be merged automatically, stop and report the blocker.
+- Do not weaken tests, remove checks, or hide failures with broad skips/xfails.
+- Keep each PR small and reviewable.
+
+Execution plan:
+1. Run docs/agent-goals/test-ci-audit.md and create a PR.
+2. Run docs/agent-goals/documentation-audit.md and create a PR.
+3. After both are merged into main, run docs/agent-goals/implementation-cleanup.md and create a PR.
+4. After the cleanup PR is created, run docs/agent-goals/maintainer-review.md as a review-only task.

ros2docker-0.1.1/docs/agent-goals/test-ci-audit.md

@@ -0,0 +1,28 @@
+Goal: Audit and improve test coverage and test execution wiring.
+
+Scope:
+
+* tests/
+* pyproject.toml or equivalent test config
+* .pre-commit-config.yaml
+* .github/workflows/*
+* README/CONTRIBUTING/DEVELOPMENT sections that describe testing
+* minimal source changes only if required to make behavior testable
+
+Tasks:
+
+* Map every public README-documented command, feature, and CLI behavior to existing tests where feasible.
+* Add missing tests for feasible documented behavior.
+* Identify behavior that cannot sensibly be tested automatically and document a manual verification check.
+* Verify that tests are collected and actually executed.
+* Check that tests are not accidentally skipped, deselected, ignored, or excluded by config.
+* Ensure skipped/xfail tests have explicit reasons.
+* Verify that local test instructions, pre-commit, CI, and release validation are consistent.
+* Do not refactor implementation except where needed to make tests possible.
+
+Run the relevant checks and report:
+
+* changed files
+* added or fixed tests
+* remaining untested behavior and why
+* commands run and results