kuberoku 0.1.0__tar.gz

kuberoku-0.1.0/.editorconfig

@@ -0,0 +1,15 @@
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+insert_final_newline = true
+trim_trailing_whitespace = true
+indent_style = space
+indent_size = 4
+
+[*.{yml,yaml,toml}]
+indent_size = 2
+
+[Makefile]
+indent_style = tab

kuberoku-0.1.0/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,32 @@
+name: Bug Report
+description: Something isn't working as expected.
+labels: ["bug"]
+body:
+  - type: textarea
+    id: what-happened
+    attributes:
+      label: What happened?
+      description: Describe the bug. What did you expect vs. what actually happened?
+    validations:
+      required: true
+
+  - type: textarea
+    id: reproduce
+    attributes:
+      label: Steps to reproduce
+      description: Minimal commands to reproduce the issue.
+      placeholder: |
+        kuberoku apps:create myapp
+        kuberoku deploy --app myapp --image nginx:1.27 --port 80/tcp
+        # error happens here
+
+  - type: textarea
+    id: environment
+    attributes:
+      label: Environment
+      description: Paste the output of the commands below.
+      placeholder: |
+        kuberoku --version
+        kubectl version
+        python --version
+        uname -a

kuberoku-0.1.0/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,17 @@
+name: Feature Request
+description: Suggest an idea or improvement.
+labels: ["enhancement"]
+body:
+  - type: textarea
+    id: description
+    attributes:
+      label: What would you like?
+      description: Describe the feature or improvement.
+    validations:
+      required: true
+
+  - type: textarea
+    id: use-case
+    attributes:
+      label: Use case
+      description: Why do you need this? What problem does it solve?

kuberoku-0.1.0/.github/workflows/compat.yml

@@ -0,0 +1,37 @@
+name: Compatibility Tests
+
+on:
+  schedule:
+    - cron: "0 6 * * 1"  # Weekly: Monday 06:00 UTC
+  workflow_dispatch:  # Manual trigger
+
+jobs:
+  compat:
+    name: Compat (kind) — K8s ${{ matrix.k8s-version }}
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        k8s-version: ["v1.33.0", "v1.34.0", "v1.35.0"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Create kind cluster
+        uses: helm/kind-action@v1
+        with:
+          cluster_name: kuberoku-compat
+          node_image: kindest/node:${{ matrix.k8s-version }}
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+
+      - name: All tests against real K8s (kind)
+        run: pytest tests/ --backend real -v

kuberoku-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,226 @@
+name: Release
+
+on:
+  push:
+    tags: ["v*"]
+
+permissions:
+  contents: read
+  actions: read
+
+jobs:
+  gate:
+    name: Release gate — verify CI passed on this commit
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Verify CI passed on this commit
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          SHA=$(git rev-parse HEAD)
+          echo "Checking CI status for commit $SHA..."
+
+          # Wait up to 5 minutes for the Tests workflow to complete (tag push may race with CI)
+          for i in $(seq 1 30); do
+            RUN_JSON=$(gh run list --commit "$SHA" --workflow "Tests" --json status,conclusion --limit 1)
+            RUN_STATUS=$(echo "$RUN_JSON" | jq -r '.[0].status // "none"')
+            RUN_CONCLUSION=$(echo "$RUN_JSON" | jq -r '.[0].conclusion // "none"')
+            echo "  Attempt $i: status=$RUN_STATUS conclusion=$RUN_CONCLUSION"
+
+            if [ "$RUN_STATUS" = "completed" ]; then
+              if [ "$RUN_CONCLUSION" = "success" ]; then
+                echo "Tests workflow passed."
+                exit 0
+              else
+                echo "::error::Tests workflow failed ($RUN_CONCLUSION). Fix tests before releasing."
+                exit 1
+              fi
+            fi
+
+            # not found or still running — wait and retry
+            sleep 10
+          done
+
+          echo "::error::Tests workflow did not complete within 5 minutes. Push to main first and wait for green CI."
+          exit 1
+
+      - name: Verify tag matches package version
+        run: |
+          TAG="${GITHUB_REF#refs/tags/v}"
+          PKG_VERSION=$(python3 -c "exec(open('src/kuberoku/_version.py').read()); print(__version__)")
+          if [ "$TAG" != "$PKG_VERSION" ]; then
+            echo "::error::Tag v${TAG} does not match _version.py (${PKG_VERSION})"
+            exit 1
+          fi
+
+  # ── Publish to PyPI ──────────────────────────────────────────────
+
+  publish:
+    name: Publish to PyPI
+    needs: gate
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      contents: read
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install build tools
+        run: python -m pip install --upgrade pip build
+
+      - name: Verify tag matches package version
+        run: |
+          TAG="${GITHUB_REF#refs/tags/v}"
+          PKG_VERSION=$(python -c "exec(open('src/kuberoku/_version.py').read()); print(__version__)")
+          if [ "$TAG" != "$PKG_VERSION" ]; then
+            echo "::error::Tag v${TAG} does not match _version.py (${PKG_VERSION})"
+            exit 1
+          fi
+
+      - name: Build sdist and wheel
+        run: python -m build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+
+  # ── Native binaries (4 targets) ─────────────────────────────────
+
+  binaries:
+    name: Binary — ${{ matrix.os }}-${{ matrix.arch }}
+    needs: gate
+    runs-on: ${{ matrix.runner }}
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - os: linux
+            arch: amd64
+            runner: ubuntu-latest
+            asset: kuberoku-linux-amd64
+          - os: darwin
+            arch: arm64
+            runner: macos-latest
+            asset: kuberoku-darwin-arm64
+          - os: darwin
+            arch: amd64
+            runner: macos-15-intel
+            asset: kuberoku-darwin-amd64
+          - os: windows
+            arch: amd64
+            runner: windows-latest
+            asset: kuberoku-windows-amd64.exe
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install .
+          pip install pyinstaller
+
+      - name: Build binary
+        run: pyinstaller kuberoku.spec
+
+      - name: Rename binary (unix)
+        if: matrix.os != 'windows'
+        run: mv dist/kuberoku dist/${{ matrix.asset }}
+
+      - name: Rename binary (windows)
+        if: matrix.os == 'windows'
+        shell: bash
+        run: mv dist/kuberoku.exe dist/${{ matrix.asset }}
+
+      - name: Smoke test
+        if: matrix.os != 'windows'
+        run: ./dist/${{ matrix.asset }} --version
+
+      - name: Smoke test (windows)
+        if: matrix.os == 'windows'
+        shell: bash
+        run: ./dist/${{ matrix.asset }} --version
+
+      - name: Upload artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: ${{ matrix.asset }}
+          path: dist/${{ matrix.asset }}
+
+  # ── Linux ARM64 via QEMU ────────────────────────────────────────
+
+  binary-linux-arm64:
+    name: Binary — linux-arm64 (QEMU)
+    needs: gate
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up QEMU
+        uses: docker/setup-qemu-action@v3
+
+      - name: Build in ARM64 container
+        run: |
+          docker run --rm --platform linux/arm64 \
+            -v "${{ github.workspace }}:/work" \
+            -w /work \
+            python:3.12-slim \
+            sh -c '
+              apt-get update && apt-get install -y --no-install-recommends binutils &&
+              pip install --upgrade pip &&
+              pip install . &&
+              pip install pyinstaller &&
+              pyinstaller kuberoku.spec &&
+              mv dist/kuberoku dist/kuberoku-linux-arm64
+            '
+
+      - name: Upload artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: kuberoku-linux-arm64
+          path: dist/kuberoku-linux-arm64
+
+  # ── GitHub Release ──────────────────────────────────────────────
+
+  release:
+    name: Create GitHub Release
+    needs: [publish, binaries, binary-linux-arm64]
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Download all artifacts
+        uses: actions/download-artifact@v4
+        with:
+          path: artifacts
+          merge-multiple: true
+
+      - name: List artifacts
+        run: ls -lhR artifacts/
+
+      - name: Create release
+        uses: softprops/action-gh-release@v2
+        with:
+          generate_release_notes: true
+          files: |
+            artifacts/kuberoku-linux-amd64
+            artifacts/kuberoku-linux-arm64
+            artifacts/kuberoku-darwin-amd64
+            artifacts/kuberoku-darwin-arm64
+            artifacts/kuberoku-windows-amd64.exe
+            scripts/install.sh
+            scripts/install.ps1

kuberoku-0.1.0/.github/workflows/tests.yml

@@ -0,0 +1,144 @@
+name: Tests
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  lint:
+    name: Lint & Type Check
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+
+      - name: Lint
+        run: ruff check src/ tests/
+
+      - name: Format check
+        run: ruff format --check src/ tests/
+
+      - name: Type check
+        run: mypy --strict src/kuberoku/
+
+  fake:
+    name: Tests (fake) — Python ${{ matrix.python-version }}
+    runs-on: ubuntu-latest
+    needs: lint
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+
+      - name: Tests with coverage
+        run: pytest tests/ -v --backend fake -n auto --dist loadfile --cov=kuberoku --cov-report=term-missing
+
+      - name: Enforce coverage threshold
+        if: matrix.python-version == '3.12'
+        run: pytest tests/ -q --backend fake -n auto --dist loadfile --cov=kuberoku --cov-fail-under=90
+
+  integration:
+    name: Tests (real) — k3d K8s ${{ matrix.k8s-version }}
+    runs-on: ubuntu-latest
+    needs: lint
+    strategy:
+      fail-fast: false
+      matrix:
+        k8s-version: ["v1.33.7", "v1.34.3", "v1.35.0"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Configure Docker for k3d insecure registry
+        run: |
+          echo '{"insecure-registries": ["k3d-registry.localhost:5000"]}' | sudo tee /etc/docker/daemon.json
+          sudo systemctl restart docker
+
+      - uses: AbsaOSS/k3d-action@v2
+        with:
+          cluster-name: kuberoku-test
+          k3d-version: v5.8.3
+          args: >-
+            --image rancher/k3s:${{ matrix.k8s-version }}-k3s1
+            --registry-create k3d-registry.localhost:5000
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+
+      - name: Setup cluster (cert-manager, etc.)
+        run: kuberoku clusters:setup
+
+      - name: All tests against real K8s
+        run: pytest tests/ --backend real -v -n4 --dist loadfile --runslow
+        env:
+          KUBEROKU_REGISTRY: k3d-registry.localhost:5000
+
+  smoke:
+    name: Smoke test (installed package)
+    needs: lint
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install from built package
+        run: |
+          python -m pip install --upgrade pip
+          pip install .
+
+      - name: Verify entry point
+        run: |
+          kuberoku --version
+          kuberoku --help
+
+      - name: Verify SDK import
+        run: |
+          python -c "from kuberoku import Kuberoku, __version__; print('SDK OK: ' + __version__)"
+
+  installer:
+    name: Test install script (multi-distro)
+    needs: lint
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install shellcheck
+        run: sudo apt-get install -y shellcheck
+
+      - name: Run installer test suite
+        run: sh scripts/test-install.sh

kuberoku-0.1.0/.gitignore

@@ -0,0 +1,35 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+*.egg
+dist/
+build/
+
+# Virtual environments
+.venv/
+venv/
+
+# Type checking / linting
+.mypy_cache/
+.ruff_cache/
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Project
+.kuberoku

kuberoku-0.1.0/CHANGELOG.md

@@ -0,0 +1,22 @@
+# Changelog
+
+## 0.1.0 (unreleased)
+
+Initial alpha release.
+
+### Added
+
+- **Apps**: create, destroy, info, rename, status, link, maintenance
+- **Config**: set, get, unset with secret masking and optimistic concurrency
+- **Deploy**: image deploy, build-from-git, multi-process types
+- **PS**: scale, restart, stop, type, set commands
+- **Releases**: info, rollback, prune with full audit trail
+- **Services**: expose, ports, logs, exec, connect, maintenance
+- **Addons**: PostgreSQL and Redis with credentials, backup, exec, connect
+- **Addon versioning**: create with `--version`, `addons:migrate` (backup → PVC wipe → restore for Postgres), `addons:migrate-rollback`
+- **Plugins**: install, uninstall, search via PyPI entry points
+- **Domains**: add, remove, clear with Ingress management
+- **Clusters**: add, remove, switch, current, info, doctor, setup
+- **Networking**: default-deny NetworkPolicies, per-process allow rules
+- **SDK**: full Python API matching CLI 1:1, frozen dataclasses, typed exceptions
+- **Distribution**: PyPI package, pre-built binaries (Linux, macOS, Windows), curl installer

kuberoku-0.1.0/CLAUDE.md

@@ -0,0 +1,98 @@
+# Agent Instructions for kuberoku
+
+Run `pytest tests/ -v && mypy src/kuberoku/ --strict && ruff check src/ tests/ && ruff format --check src/ tests/` to verify any file edits before prompting for input.
+
+## What this is
+
+Kuberoku is a Python CLI + SDK that gives developers Heroku-like DX on vanilla Kubernetes. Zero server-side components — CLI/SDK only, K8s is the database. The complete specification is in `docs/NORTHSTAR.txt` (~8000 lines, 19 sections).
+
+## Architecture (strict three-layer)
+
+```
+CLI (Click)  -->  SDK (business logic)  -->  K8s (protocol + client)
+```
+
+- **CLI never touches K8s directly.** Calls one SDK method, formats the result.
+- **SDK never prints.** Returns frozen dataclasses, raises typed exceptions, progress via `on_step` callback.
+- **K8s client returns `dict[str, Any]`.** No K8s model objects leak upward. `typing.Protocol` defines the interface.
+- **KuberokuFactory** is the DI container. Tests inject `FakeK8sClient`.
+
+## Required before each commit
+
+```bash
+pytest tests/ -v                    # tests pass
+mypy src/kuberoku/ --strict         # types check
+ruff check src/ tests/              # lint clean
+ruff format --check src/ tests/     # format clean
+```
+
+## Source layout
+
+```
+src/kuberoku/
+    branding.py          # TOOL_NAME + all derived constants (single source)
+    models.py            # Frozen dataclasses (App, Release, Dyno, etc.)
+    exceptions.py        # KuberokuError hierarchy
+    factory.py           # KuberokuFactory (DI container)
+    client.py            # Public facade: from kuberoku import Kuberoku
+    k8s/
+        protocols.py     # K8sClientProtocol (typing.Protocol)
+        client.py        # Real K8s client (wraps kubernetes library)
+        labels.py        # Label builders: for_app(), for_process(), selector()
+        resources.py     # Resource dict builders: build_deployment(), safe_name()
+    sdk/                 # One service per command group (apps.py, config.py, deploy.py, ...)
+    cli/                 # One file per command group, mirrors sdk/ 1:1
+        main.py          # ColonCommandGroup (colon commands), root group, entry point
+tests/
+    backends/fake.py     # FakeK8sClient (in-memory, implements K8sClientProtocol)
+    {feature}/           # tests/{apps,config,deploy,...}/test_{command}.py
+    infrastructure/      # tests for labels, resources, models, branding, factory
+    contract/            # FakeK8sClient matches real K8s behavior
+```
+
+## Key rules
+
+- **Branding**: All identity constants derive from `branding.py`. No hardcoded "kuberoku" strings elsewhere.
+- **Resource names**: `{PREFIX}-{type}-{app}[-{suffix}]`. Use `safe_name()` for 63-char K8s limit.
+- **Labels**: `{DOMAIN}/managed-by`, `{DOMAIN}/app`, `{DOMAIN}/process-type`. See `k8s/labels.py`.
+- **Optimistic concurrency**: All ConfigMap/Secret updates use `resourceVersion` + retry on 409.
+- **Colon commands**: `apps:create` and `apps create` both work via `ColonCommandGroup.resolve_command()`.
+- **LazyGroup**: Don't import sdk/ or k8s/ at CLI module level. Keeps `--help` under 100ms.
+- **Cross-platform**: pathlib everywhere, no `shell=True`. Windows + Linux + macOS.
+
+## Development workflow (TDD per command)
+
+1. Write `tests/{feature}/test_{command}.py` first — SDK + CLI tests in same file
+2. Implement SDK method in `src/kuberoku/sdk/`
+3. Wire CLI command in `src/kuberoku/cli/`
+4. Verify: tests, mypy, ruff all pass
+
+## NORTHSTAR.txt section index
+
+Read the relevant section when you need deeper context:
+
+- Section 1: Vision & positioning
+- Section 2: Branding & naming
+- Section 3: End-to-end user experience
+- Section 4: Command reference (all 62 commands)
+- Section 5: Colon command implementation
+- Section 6: SDK API design
+- Section 7: Non-HTTP services & multi-port
+- Section 8: Networking
+- Section 9: Architecture & data storage
+- Section 10: Data models
+- Section 11: Exception hierarchy
+- Section 12: Testing strategy (backends, fixtures, contract tests, TDD workflow)
+- Section 13: Dependencies
+- Section 14: Distribution
+- Section 15: Plugin system
+- Section 16: Implementation phases (0-14)
+- Section 17: Cross-platform
+- Section 18: Error UX
+- Section 19: CI pipeline
+
+## Dependencies
+
+- Runtime: click >=8.1, kubernetes >=35, rich >=13, pyyaml >=6
+- Dev: pytest, pytest-cov, pytest-mock, mypy (--strict), ruff, vulture, pip-audit, types-PyYAML
+- Build: hatchling. Entry point: `kuberoku = "kuberoku.cli.main:run"`

kuberoku-0.1.0/CODEOWNERS

@@ -0,0 +1,2 @@
+# Default owner for everything
+* @amanjain