rots 0.4.0__tar.gz

rots-0.4.0/.git

@@ -0,0 +1 @@
+gitdir: ../../.git/modules/deployments/containers

rots-0.4.0/.github/workflows/ci.yml

@@ -0,0 +1,116 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ['3.11', '3.12', '3.13']
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: uv sync --frozen --extra test
+
+      - name: Run tests with coverage
+        run: |
+          uv run pytest tests/ \
+            --ignore=tests/integration \
+            --cov=rots \
+            --cov-report=term-missing \
+            --cov-report=xml \
+            --cov-fail-under=70
+
+      - name: Check per-file coverage minimums
+        run: |
+          # cli.py: baseline 26% (target: 80% — add tests for subcommand registration)
+          uv run python -m coverage report \
+            --include="*/rots/cli.py" \
+            --fail-under=26
+          # commands/db.py: baseline 29% (target: 70% — add tests for deploy history queries)
+          uv run python -m coverage report \
+            --include="*/rots/commands/db.py" \
+            --fail-under=29
+
+      - name: Upload coverage to Codecov
+        if: matrix.python-version == '3.11'
+        uses: codecov/codecov-action@v4
+        with:
+          files: ./coverage.xml
+          fail_ci_if_error: false
+          verbose: true
+
+  integration:
+    # Integration smoke tests run on ubuntu-latest where systemd and podman
+    # are available. Tests skip gracefully when prerequisites are absent.
+    # This job is allowed to fail without blocking the PR (continue-on-error).
+    runs-on: ubuntu-latest
+    needs: test
+    continue-on-error: true
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+
+      - name: Set up Python 3.11
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+
+      - name: Install dependencies
+        run: uv sync --frozen --extra test
+
+      - name: Run integration smoke tests
+        run: |
+          uv run pytest tests/integration/ -v \
+            --tb=short \
+            --no-header
+
+  lint:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+
+      - name: Install dependencies
+        run: uv sync --frozen --extra dev
+
+      - name: Run ruff linter
+        run: uv run ruff check src/
+
+      - name: Run ruff formatter check
+        run: uv run ruff format --check src/
+
+      - name: Run pyright
+        run: uv run pyright src/

rots-0.4.0/.github/workflows/claude-code-review.yml

@@ -0,0 +1,100 @@
+# .github/workflows/claude-code-review.yml
+
+name: Claude Code Review
+
+on:
+  pull_request:
+    branches:
+      - 'feature/*'
+      - 'fix/*'
+      - 'wip/*'
+      - 'rel/*'
+      - 'develop'
+      - 'main'
+    types: [opened, synchronize, labeled]
+  workflow_dispatch:
+
+jobs:
+  claude-review:
+    # Optional: Filter by PR author
+    # if: |
+    #   github.event.pull_request.user.login == 'external-contributor' ||
+    #   github.event.pull_request.user.login == 'new-developer' ||
+    #   github.event.pull_request.author_association == 'FIRST_TIME_CONTRIBUTOR'
+    # if: ${{ !startsWith(github.head_ref, 'deps/') }}
+    runs-on: ubuntu-latest
+    # Skip bot-created PRs (renovate, dependabot, etc.) - they show as 'name[bot]' in github.actor
+    if: ${{
+      !endsWith(github.actor, '[bot]') &&
+      (
+        (github.event.action == 'opened') ||
+        (github.event.action == 'labeled' && github.event.label.name == 'claude-review') ||
+        (github.event.action == 'synchronize' && contains(github.event.pull_request.labels.*.name, 'claude-review'))
+      )
+      }}
+
+    permissions:
+      contents: read
+      pull-requests: read
+      issues: read
+      id-token: write
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+        with:
+          fetch-depth: 1
+
+      - name: Run Claude Code Review
+        id: claude-review
+        uses: anthropics/claude-code-action@beta
+        with:
+          claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
+
+          # Optional: Specify model (defaults to Claude Sonnet 4, uncomment for Claude Opus 4)
+          # model: "claude-opus-4-20250514"
+
+          # Direct prompt for automated review (no @claude mention needed)
+          direct_prompt: |
+            Please review this pull request and provide feedback on:
+            - Code quality and best practices
+            - Potential bugs or issues
+            - Performance considerations
+            - Security concerns
+            - Test coverage
+
+            Be constructive and helpful in your feedback.
+
+          # Optional: Use sticky comments to make Claude reuse the same comment on subsequent pushes to the same PR
+          use_sticky_comment: true
+
+          # Optional: Different prompts for different authors
+          # direct_prompt: |
+          #   ${{ github.event.pull_request.author_association == 'FIRST_TIME_CONTRIBUTOR' &&
+          #   'Welcome! Please review this PR from a first-time contributor. Be encouraging and provide detailed explanations for any suggestions.' ||
+          #   'Please provide a thorough code review focusing on our coding standards and best practices.' }}
+
+          # Optional: Add specific tools for running tests or linting
+          # allowed_tools: "Bash(npm run test),Bash(npm run lint),Bash(npm run typecheck)"
+
+          # Optional: Skip review for certain conditions
+          # if: |
+          #   !contains(github.event.pull_request.title, '[skip-review]') &&
+          #   !contains(github.event.pull_request.title, '[WIP]')
+
+      - name: Remove claude-review label
+        # Remove label whether success or failure - prevents getting stuck
+        if: always() && github.event.action != 'opened'
+        uses: actions/github-script@v7
+        with:
+          script: |
+            try {
+              await github.rest.issues.removeLabel({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                issue_number: context.issue.number,
+                name: 'claude-review'
+              });
+            } catch (error) {
+              console.log('Label not found or already removed');
+            }

rots-0.4.0/.github/workflows/claude.yml

@@ -0,0 +1,77 @@
+# .github/workflows/claude.yml
+
+name: Claude Code
+
+on:
+  pull_request:
+    branches:
+      - 'feature/*'
+      - 'fix/*'
+      - 'wip/*'
+      - 'rel/*'
+      - 'develop'
+      - 'main'
+  issue_comment:
+    types: [created]
+  pull_request_review_comment:
+    types: [created]
+  issues:
+    types: [opened, assigned]
+  pull_request_review:
+    types: [submitted]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  claude:
+    if: |
+      (github.event_name == 'issue_comment' && contains(github.event.comment.body, '@claude')) ||
+      (github.event_name == 'pull_request_review_comment' && contains(github.event.comment.body, '@claude')) ||
+      (github.event_name == 'pull_request_review' && contains(github.event.review.body, '@claude')) ||
+      (github.event_name == 'issues' && (contains(github.event.issue.body, '@claude') || contains(github.event.issue.title, '@claude')))
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      pull-requests: read
+      issues: read
+      id-token: write
+      actions: read # Required for Claude to read CI results on PRs
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+        with:
+          fetch-depth: 1
+
+      - name: Run Claude Code
+        id: claude
+        uses: anthropics/claude-code-action@beta
+        with:
+          claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
+
+          # This is an optional setting that allows Claude to read CI results on PRs
+          additional_permissions: |
+            actions: read
+
+          # Optional: Specify model (defaults to Claude Sonnet 4, uncomment for Claude Opus 4)
+          # model: "claude-opus-4-20250514"
+
+          # Optional: Customize the trigger phrase (default: @claude)
+          # trigger_phrase: "/claude"
+
+          # Optional: Trigger when specific user is assigned to an issue
+          # assignee_trigger: "claude-bot"
+
+          # Optional: Allow Claude to run specific commands
+          # allowed_tools: "Bash(npm install),Bash(npm run build),Bash(npm run test:*),Bash(npm run lint:*)"
+
+          # Optional: Add custom instructions for Claude to customize its behavior for your project
+          # custom_instructions: |
+          #   Follow our coding standards
+          #   Ensure all new code has tests
+          #   Use TypeScript for new files
+
+          # Optional: Custom environment variables for Claude
+          # claude_env: |
+          #   NODE_ENV: test

rots-0.4.0/.github/workflows/release.yml

@@ -0,0 +1,34 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - 'v*'
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+
+      - name: Build package
+        run: uv build
+
+      - name: Create GitHub Release
+        uses: softprops/action-gh-release@v1
+        with:
+          files: dist/*
+          generate_release_notes: true

rots-0.4.0/.gitignore

@@ -0,0 +1,30 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# Distribution / packaging
+dist/
+build/
+*.egg-info/
+*.egg
+
+# Virtual environments
+.venv/
+venv/
+ENV/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+*.txt
+
+# OS
+.DS_Store
+Thumbs.db
+
+.claude
+.serena
+.coverage

rots-0.4.0/.pre-commit-config.yaml

@@ -0,0 +1,113 @@
+##
+# Pre-Commit Hooks Configuration
+#
+# Fast, lightweight code quality checks that run before each commit
+#
+# Setup:
+#   1. Install pre-commit:
+#       $ pip install pre-commit
+#
+#   2. Install git hooks:
+#       $ pre-commit install
+#
+# Usage:
+#   Hooks run automatically on 'git commit'
+#
+#   Manual commands:
+#   - Check all files:
+#     $ pre-commit run --all-files
+#
+#   - Update hooks:
+#     $ pre-commit autoupdate
+#
+#   - Reinstall after config changes:
+#     $ pre-commit install
+#
+# Best Practices:
+#   - Reinstall hooks after modifying this config
+#   - Commit config changes in isolation
+#   - Keep checks fast to maintain workflow
+#
+# Resources:
+#   - Docs: https://pre-commit.com
+#   - Available hooks: https://pre-commit.com/hooks.html
+
+# Hook installation configuration
+default_install_hook_types:
+  - pre-commit # Primary code quality checks
+  - prepare-commit-msg # Commit message preprocessing
+  - post-commit # Actions after successful commit
+  - post-checkout # Triggered after git checkout
+  - post-merge # Triggered after git merge
+
+# Default execution stage
+default_stages: [pre-commit]
+
+# Allow all hooks to run even if one (or more fails). This avoids
+# the commit->fail->fix->commit->fail->fix->commit routine.
+fail_fast: false
+
+repos:
+  # Meta hooks: basic checks for pre-commit config itself
+  - repo: meta
+    hooks:
+      - id: check-hooks-apply
+      - id: check-useless-excludes
+
+  # Standard pre-commit hooks: lightweight, universal checks
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v5.0.0
+    hooks:
+      # Formatting and basic sanitization
+      - id: trailing-whitespace # Remove trailing whitespaces
+      - id: end-of-file-fixer # Ensure files end with newline
+      - id: check-merge-conflict # Detect unresolved merge conflicts
+      - id: detect-private-key # Warn about committing private keys
+      - id: check-added-large-files # Prevent committing oversized files
+        args: ["--maxkb=2500"] # 2.5MB file size threshold
+      - id: no-commit-to-branch # Prevent direct commits to critical branches
+        args: ["--branch", "main"]
+
+  # Commit message issue tracking integration
+  - repo: https://github.com/delano/add-msg-issue-prefix-hook
+    rev: v0.0.14-fork
+    hooks:
+      - id: add-msg-issue-prefix
+        stages: [prepare-commit-msg]
+        description: Automatically prefix commits with issue numbers
+        args:
+          - "--default="
+          - "--exclude-pattern=^(dependabot|renovate)/"
+          - "--pattern=(i18n(?=/)|([a-zA-Z0-9]{0,10}-?[0-9]{1,5}))"
+          - "--template=[#{}]"
+
+  # Pyright - static type checking (matches IDE)
+  # Only checks changed files rather than all of src/ for speed
+  - repo: https://github.com/RobertCraigie/pyright-python
+    rev: v1.1.390
+    hooks:
+      - id: pyright
+        files: ^src/
+        additional_dependencies:
+          - cyclopts>=3.9
+          - pytest>=8.0
+
+  # Ruff - fast linting and formatting
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.9.2
+    hooks:
+      - id: ruff
+        args: [--fix]
+      - id: ruff-format
+
+  # pytest - run before push with coverage and last-failed optimization
+  # Skipped on commit for speed; full suite gates push instead
+  - repo: local
+    hooks:
+      - id: pytest-cov
+        name: pytest-cov
+        entry: .venv/bin/pytest tests/ -x -q --ff --cov=rots --cov-report=term-missing --cov-fail-under=70
+        language: system
+        pass_filenames: false
+        files: ^(src/|tests/).*\.py$
+        stages: [pre-push]

rots-0.4.0/CHANGELOG.rst

@@ -0,0 +1,13 @@
+CHANGELOG
+=========
+
+All notable changes to rots are documented here.
+
+The format is based on `Keep a
+Changelog <https://keepachangelog.com/en/1.1.0/>`__, and this project
+adheres to `Semantic
+Versioning <https://semver.org/spec/v2.0.0.html>`__.
+
+.. raw:: html
+
+   <!--scriv-insert-here-->

rots-0.4.0/CLAUDE.md

@@ -0,0 +1,96 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Build & Test Commands
+
+```bash
+# Install for development (editable)
+pip install -e ".[dev,test]"
+
+# Run all tests
+pytest tests/
+
+# Run single test file
+pytest tests/test_quadlet.py
+
+# Run single test by name
+pytest tests/test_quadlet.py -k "test_template"
+
+# Run service management tests
+pytest tests/test_service.py
+
+# Run cloud-init tests
+pytest tests/commands/cloudinit/
+
+# Run tests with coverage (CI threshold: 70%)
+pytest tests/ --cov=rots --cov-report=term-missing --cov-fail-under=70
+
+# IMPORTANT: See docs/TESTING.md for testing patterns
+# Key rule: mock responses must use tmp_path, not real system paths
+
+# Lint and format
+ruff check src/
+ruff format src/
+ruff check src/ --fix  # auto-fix
+
+# Type checking
+pyright src/
+
+# Pre-commit hooks (auto-installed)
+pre-commit run --all-files
+```
+
+## Git Notes
+
+When running git commands with long output, use `git --no-pager diff` etc.
+
+## Architecture
+
+This is a dual-purpose service orchestration tool:
+
+1. **Container management**: OneTimeSecret containers via Podman Quadlets (systemd integration)
+2. **Service management**: Native systemd services for dependencies (Valkey, Redis)
+
+### Core Modules (`src/rots/`)
+
+- **cli.py** - Entry point (`app`), registers subcommand groups
+- **config.py** - `Config` dataclass: image, tag, paths. Reads from env vars (IMAGE, TAG, etc.)
+- **quadlet.py** - Writes systemd Quadlet template to `/etc/containers/systemd/onetime@.container`
+- **systemd.py** - Wrappers around `systemctl`: start/stop/restart/status, `discover_instances()` for auto-detection
+- **podman.py** - `Podman` class: chainable interface to podman CLI (e.g., `podman.container.ls()`)
+- **assets.py** - Extracts `/app/public` from container image to shared volume
+
+### Commands (`src/rots/commands/`)
+
+#### Container Commands
+
+- **instance.py** - Main operations: `deploy`, `redeploy`, `undeploy`, `start`, `stop`, `restart`, `status`, `logs`, `list`
+- **assets.py** - `sync` command for static asset updates
+- **image.py** - Container image management
+- **proxy.py** - Caddy reverse proxy configuration
+
+#### Service Commands (`service/`)
+
+- **app.py** - Service lifecycle: `init`, `start`, `stop`, `restart`, `status`, `logs`, `enable`, `disable`, `list_instances`
+- **packages.py** - Service package definitions: `VALKEY`, `REDIS` with config paths, secrets handling, systemd templates
+- **\_helpers.py** - Shared utilities: config file management, secrets creation, systemctl wrappers
+
+#### Cloud-Init Commands (`cloudinit/`)
+
+- **app.py** - Cloud-init generation: `generate`, `validate`
+- **templates.py** - DEB822-style apt sources templates for Debian 13 (Trixie), PostgreSQL, and Valkey repositories
+
+### Key Patterns
+
+- Uses **cyclopts** for CLI framework (decorators like `@app.command()`)
+- **Port-based instance identification**: Each instance runs on a specific port (e.g., 7043 for containers, 6379 for services)
+- **Container auto-discovery**: `systemd.discover_instances()` finds running `onetime@*` services
+- **Container env templating**: `/etc/onetimesecret/.env` → `/var/lib/onetimesecret/.env-{port}` (FHS-compliant)
+- **Service config copy-on-write**: Package defaults (`/etc/valkey/valkey.conf`) → instance configs (`/etc/valkey/instances/6379.conf`)
+- **Service secrets separation**: Sensitive data in separate files with restricted permissions (mode 0640, owned by service user)
+- **Package-provided templates**: Uses existing systemd templates (`valkey-server@.service`) rather than creating custom units
+- ## Verification
+  Don't invent technical rationales. When working with runtime behavior, get or
+  ask for actual output (podman ps, systemctl status, etc.) before changing code.
+  Documentation and memories are not substitutes for verified information.

rots-0.4.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) Onetime Secret
+
+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.