ots-containers 0.3.0__tar.gz

ots_containers-0.3.0/.claude/settings.local.json

@@ -0,0 +1,42 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(pytest:*)",
+      "Bash(python -m pytest:*)",
+      "Bash(git --no-pager log --oneline -4)",
+      "Bash(git --no-pager log --oneline -20 /Users/d/Projects/opensource/onetime/ots-containers)",
+      "Bash(python -m ots_containers.cli:*)",
+      "Bash(python:*)",
+      "Bash(pyright:*)",
+      "Bash(ruff check:*)",
+      "Bash(git --no-pager log --oneline -3)",
+      "Bash(pip install:*)",
+      "Bash(ots-containers cloudinit generate:*)",
+      "Bash(ots-containers cloudinit:*)",
+      "Bash(ruff format:*)",
+      "Bash(SKIP=pytest git commit -m \"Fix Valkey template service config path for Debian convention\n\n- Update ServicePackage to support both subdirectory and flat config layouts\n- Add use_instances_subdir flag to control directory structure\n- Change Valkey config pattern to valkey-{instance}.conf \\(Debian template expects /etc/valkey/valkey-%i.conf\\)\n- Update secrets file pattern to match: valkey-{instance}.secrets\n- Fix ensure_instances_dir\\(\\) to handle both directory structures\n- Update list_instances to correctly parse instance names from both patterns\n- Add check_default_service_conflict\\(\\) to warn about running default service\n- Integrate default service check into init command\n\nResolves issue where valkey-server@6380.service failed with:\n  ''Fatal error, can''t open config file /etc/valkey/valkey-6380.conf''\n\nThe Debian systemd template expects configs at /etc/valkey/valkey-{port}.conf,\nnot /etc/valkey/instances/{port}.conf as our code was creating.\")",
+      "Bash(SKIP=pytest git commit --no-gpg-sign -m \"Fix Valkey template service config path for Debian convention\n\n- Update ServicePackage to support both subdirectory and flat config layouts\n- Add use_instances_subdir flag to control directory structure\n- Change Valkey config pattern to valkey-{instance}.conf \\(Debian template expects /etc/valkey/valkey-%i.conf\\)\n- Update secrets file pattern to match: valkey-{instance}.secrets\n- Fix ensure_instances_dir\\(\\) to handle both directory structures\n- Update list_instances to correctly parse instance names from both patterns\n- Add check_default_service_conflict\\(\\) to warn about running default service\n- Integrate default service check into init command\n\nResolves issue where valkey-server@6380.service failed with:\n  ''Fatal error, can''t open config file /etc/valkey/valkey-6380.conf''\n\nThe Debian systemd template expects configs at /etc/valkey/valkey-{port}.conf,\nnot /etc/valkey/instances/{port}.conf as our code was creating.\")",
+      "Bash(SKIP=pytest-cov git push)",
+      "Bash(.venv/bin/python:*)",
+      "Bash(.venv/bin/pip install:*)",
+      "Bash(.venv/bin/pytest tests/ -x -q)",
+      "Bash(.venv/bin/pytest tests/test_quadlet.py -x -q)",
+      "Bash(.venv/bin/pytest tests/ -q)",
+      "Bash(git --no-pager log --oneline -10)",
+      "Bash(caddy version:*)",
+      "Bash(caddy list-modules:*)",
+      "Bash(podman image inspect:*)",
+      "Bash(git --no-pager log main..HEAD --oneline)",
+      "Bash(git --no-pager branch:*)",
+      "Bash(git --no-pager log jan20..HEAD --oneline)",
+      "Bash(git --no-pager log delano/dec16..HEAD --oneline)"
+    ],
+    "enableAllProjectMcpServers": true,
+    "enabledMcpjsonServers": [
+      "kagi",
+      "serena",
+      "context7"
+    ],
+    "includeCoAuthoredBy": false
+  }
+}

ots_containers-0.3.0/.github/workflows/ci.yml

@@ -0,0 +1,69 @@
+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: 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 ".[test]"
+
+      - name: Run tests with coverage
+        run: |
+          pytest tests/ \
+            --cov=ots_containers \
+            --cov-report=term-missing \
+            --cov-report=xml \
+            --cov-fail-under=70
+
+      - 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
+
+  lint:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install ruff pyright
+          pip install -e ".[dev]"
+
+      - name: Run ruff linter
+        run: ruff check src/
+
+      - name: Run ruff formatter check
+        run: ruff format --check src/
+
+      - name: Run pyright
+        run: pyright src/

ots_containers-0.3.0/.github/workflows/claude-code-review.yml

@@ -0,0 +1,95 @@
+# .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
+    if: |
+      (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');
+            }

ots_containers-0.3.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

ots_containers-0.3.0/.github/workflows/release.yml

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

ots_containers-0.3.0/.gitignore

@@ -0,0 +1,28 @@
+# 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
+
+.coverage

ots_containers-0.3.0/.pre-commit-config.yaml

@@ -0,0 +1,122 @@
+##
+# 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)
+  - repo: https://github.com/RobertCraigie/pyright-python
+    rev: v1.1.390
+    hooks:
+      - id: pyright
+        args: [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.8.3
+    hooks:
+      - id: ruff
+        args: [--fix]
+      - id: ruff-format
+
+  # pytest - run tests before commit (fast, no coverage)
+  # Only runs when Python files in src/ or tests/ are modified
+  - repo: local
+    hooks:
+      - id: pytest
+        name: pytest
+        entry: .venv/bin/pytest tests/ -x -q
+        language: system
+        pass_filenames: false
+        files: ^(src/|tests/).*\.py$
+        stages: [pre-commit]
+
+      # pytest with coverage - run before push
+      # Only runs when Python files in src/ or tests/ are modified
+      - id: pytest-cov
+        name: pytest-cov
+        entry: .venv/bin/pytest tests/ -x -q --cov=ots_containers --cov-report=term-missing --cov-fail-under=70
+        language: system
+        pass_filenames: false
+        files: ^(src/|tests/).*\.py$
+        stages: [pre-push]

ots_containers-0.3.0/.serena/.gitignore

@@ -0,0 +1,2 @@
+/cache
+*

ots_containers-0.3.0/.serena/memories/1215-dbus-conversion-technical-notes.md

@@ -0,0 +1,81 @@
+# D-Bus Conversion Technical Notes (2025-12-15)
+
+## Issue Reference
+https://github.com/onetimesecret/ots-containers/issues/1
+
+## Problem Context
+
+The `systemd.py` module parses `systemctl` CLI output, which caused a production bug:
+- `discover_instances()` returned failed units as "running"
+- Root cause: didn't parse ACTIVE/SUB state columns, only matched unit names
+- Fixed in commit 614099e but parsing remains fragile
+
+## D-Bus vs CLI
+
+systemd's official API is D-Bus. CLI tools are wrappers. Key advantages:
+- Structured data (properties, not text)
+- Stable API across versions
+- Better testability (mock D-Bus interface)
+- Proper async job handling for start/stop operations
+
+## Implementation Notes
+
+### Library Choice
+
+**Recommend pystemd**:
+- Facebook/Meta maintained
+- Direct systemd bindings
+- Used in production at scale
+- `pip install pystemd` (requires libsystemd-dev)
+
+### Key D-Bus Concepts
+
+Manager object: `/org/freedesktop/systemd1`
+- `ListUnits()` - Returns array of unit info tuples
+- `StartUnit(name, mode)` - Returns job path
+- `StopUnit(name, mode)` - Returns job path
+- `Reload()` - Daemon reload
+
+Unit properties (org.freedesktop.systemd1.Unit):
+- `ActiveState`: "active" | "inactive" | "failed" | "activating" | "deactivating"
+- `SubState`: "running" | "dead" | "failed" | "exited" | etc.
+- `LoadState`: "loaded" | "not-found" | "masked"
+
+### Migration Strategy
+
+1. Add pystemd dependency
+2. Create `_dbus.py` module with D-Bus implementation
+3. Update `systemd.py` to use D-Bus by default
+4. Keep CLI fallback for environments without D-Bus access
+5. Update tests to mock D-Bus interface
+
+### Test Considerations
+
+pystemd can be mocked:
+```python
+@pytest.fixture
+def mock_manager(mocker):
+    manager = mocker.Mock()
+    manager.list_units.return_value = [
+        (b"onetime@7043.service", b"", b"loaded", b"active", b"running", ...),
+    ]
+    mocker.patch("pystemd.systemd1.Manager", return_value=manager)
+    return manager
+```
+
+### Async Operations
+
+Start/Stop/Restart are async in systemd. Current code uses `check=True` which waits.
+D-Bus returns a job path; need to either:
+- Poll job status until complete
+- Use synchronous convenience methods if available
+- Accept fire-and-forget for some operations
+
+## Related Commits
+
+- 614099e: Filter discover_instances to only return running units (the parsing fix)
+- 5078405: Fix container naming (another verification failure)
+
+## Branch Context
+
+Work on `delano/next` branch. Issue #1 created for tracking.

ots_containers-0.3.0/.serena/memories/1216-ots-service-command-design.md

@@ -0,0 +1,107 @@
+# ots service Command Design - December 2024
+
+## Overview
+
+Design for managing systemd template services (e.g., `valkey-server@.service`) on Debian 13 systems. Uses package-provided templates rather than custom unit files.
+
+## Command Structure
+
+```bash
+ots service init valkey 6379       # Full setup wizard
+ots service enable valkey 6380     # Add another instance
+ots service disable valkey 6379    # Stop/disable instance
+ots service status valkey 6379     # Show systemd status
+ots service logs valkey 6379       # journalctl wrapper
+ots service list valkey            # Auto-discover instances
+ots service doctor valkey 6379     # Comprehensive health check
+ots service reconcile valkey       # Detect DB vs systemctl drift
+ots service adopt valkey 6379      # Bring manual units under management
+ots service forget valkey 6379     # Remove phantom DB records
+ots service secret-set valkey 6379 requirepass
+ots service secret-rotate valkey 6379 requirepass
+```
+
+## Key Design Decisions
+
+### 1. Config File Management
+- **Strategy**: Copy-on-write with `/etc/<pkg>/instances/` subdirectory
+- Avoids dpkg conffile conflicts on package upgrades
+- Package base config (`/etc/valkey/valkey.conf`) treated as readonly reference
+
+### 2. Source of Truth
+- **systemctl** = runtime state (is-active, is-enabled, list-units)
+- **SQLite database** = metadata (config paths, ports, timestamps, audit trail)
+- Use `systemctl --output=json` on Debian 13 (systemd 255+) for robustness
+
+### 3. Secret Handling (Three Tiers)
+- **inline**: Secrets in main config (mode 0600)
+- **separate** (default): `.conf` + `.secrets` files
+- **credential**: systemd LoadCredential= directive
+
+### 4. FHS Compliance
+- Config: `/etc/<pkg>/instances/{instance}.conf`
+- Secrets: `/etc/<pkg>/instances/{instance}.secrets` (mode 0600)
+- Data: `/var/lib/<pkg>/{instance}/`
+
+## Database Schema
+
+```sql
+service_instances (package, instance, config_file, data_dir, port, created_at)
+service_actions (timestamp, package, instance, action, success, notes)
+```
+
+## ServicePackage Registry Pattern
+
+```python
+@dataclass
+class SecretConfig:
+    secret_keys: list[str]
+    secrets_file_pattern: str | None
+    include_directive: str | None
+    config_with_secrets_mode: int = 0o600
+    secrets_file_mode: int = 0o600
+    secrets_owned_by_service: bool = True
+
+@dataclass
+class ServicePackage:
+    name: str
+    template: str                    # e.g., "valkey-server@"
+    config_dir: Path                 # /etc/valkey
+    data_dir: Path                   # /var/lib/valkey
+    config_file_pattern: str         # "{instance}.conf"
+    default_service: str | None      # "valkey-server.service"
+    default_config: Path | None      # /etc/valkey/valkey.conf
+    secrets: SecretConfig | None
+    # ... additional fields
+```
+
+## Doctor Command Checks
+
+1. `systemd_syntax` - systemd-analyze verify
+2. `security_score` - systemd-analyze security
+3. `config_file` - exists, correct permissions
+4. `secrets_file` - 0600, correct ownership
+5. `data_directory` - exists, correct ownership
+6. `runtime_status` - active + enabled
+7. `db_sync` - DB matches systemctl
+
+## File Structure
+
+```
+src/ots_containers/commands/service/
+    __init__.py
+    app.py           # Main commands
+    packages.py      # ServicePackage registry
+    _helpers.py      # Config/secret helpers
+    db.py            # Database operations (extend existing)
+```
+
+## Ops Standards Review Result
+
+- ✅ FHS Compliance: 10/10
+- ✅ systemd Integration: 9/10
+- ⚠️ Security: Addressed with secret handling
+- ✅ Maintainability: 9/10 (reconcile/adopt pattern)
+
+## Related Memories
+- fhs-directory-standards (comprehensive FHS research)