cutip-blocks 0.1.0__tar.gz

cutip_blocks-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,155 @@
+name: CI
+
+on:
+  push:
+    branches:
+      - "feat/**"
+      - "bug/**"
+      - "claude/**"
+  pull_request:
+    types: [opened, synchronize, reopened]
+    branches:
+      - staging
+      - integration
+
+jobs:
+  # ── Auto-label and assign on PR open ────────────────────────────────────────
+  auto-label:
+    name: Label & Assign PR
+    runs-on: ubuntu-latest
+    if: github.event_name == 'pull_request' && github.event.action == 'opened'
+
+    permissions:
+      pull-requests: write
+
+    steps:
+      - name: Apply label and assignee
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          PR="${{ github.event.pull_request.number }}"
+          BRANCH="${{ github.head_ref }}"
+          AUTHOR="${{ github.event.pull_request.user.login }}"
+
+          gh pr edit "$PR" --repo "${{ github.repository }}" --add-assignee "$AUTHOR"
+
+          if echo "$BRANCH" | grep -qE '^feat/'; then
+            LABEL="feature"; COLOR="0075ca"
+          elif echo "$BRANCH" | grep -qE '^bug/'; then
+            LABEL="bugfix"; COLOR="d73a4a"
+          elif echo "$BRANCH" | grep -qE '^docs/'; then
+            LABEL="documentation"; COLOR="006b75"
+          else
+            LABEL="feature"; COLOR="0075ca"
+          fi
+
+          gh label create "$LABEL" --color "$COLOR" --force --repo "${{ github.repository }}" 2>/dev/null || true
+          gh pr edit "$PR" --repo "${{ github.repository }}" --add-label "$LABEL"
+
+  # ── Lint ────────────────────────────────────────────────────────────────────
+  lint:
+    name: Ruff Lint & Format
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          version: "latest"
+
+      - name: Install dependencies
+        run: uv sync
+
+      - name: Ruff check
+        run: uv run ruff check .
+
+      - name: Ruff format check
+        run: uv run ruff format --check .
+
+  # ── Type Check ──────────────────────────────────────────────────────────────
+  type-check:
+    name: Type Check (ty)
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          version: "latest"
+
+      - name: Install dependencies
+        run: uv sync
+
+      - name: Run ty
+        run: uv run ty check cutip_blocks/
+
+  # ── Unit Tests ──────────────────────────────────────────────────────────────
+  unit-tests:
+    name: Unit Tests
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          version: "latest"
+
+      - name: Install dependencies
+        run: uv sync
+
+      - name: Run tests
+        run: uv run pytest tests/ -v
+
+  # ── Smoke Test ──────────────────────────────────────────────────────────────
+  smoke-test:
+    name: Smoke Test
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          version: "latest"
+
+      - name: Build wheel
+        run: uv build --wheel
+
+      - name: Smoke-test import
+        run: |
+          uv venv .wheel-test
+          uv pip install --python .wheel-test/bin/python dist/cutip_blocks-*.whl
+          .wheel-test/bin/python -c "
+          from cutip_blocks import BlockRegistry
+          r = BlockRegistry.discover()
+          assert len(r.blocks) >= 30, f'Expected 30+ blocks, got {len(r.blocks)}'
+          print(f'OK: {len(r.blocks)} blocks across {len(r.categories())} categories')
+          "
+
+  # ── Docs Build ──────────────────────────────────────────────────────────────
+  docs-build:
+    name: Docs Build
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          version: "latest"
+
+      - name: Install docs dependencies
+        run: |
+          uv venv .venv
+          uv pip install mkdocs-material "mkdocs<2.0" mkdocs-callouts
+
+      - name: Build docs (strict)
+        run: uv run mkdocs build --strict

cutip_blocks-0.1.0/.github/workflows/integration.yml

@@ -0,0 +1,38 @@
+name: Integration
+
+on:
+  push:
+    branches:
+      - integration
+
+jobs:
+  prune:
+    name: Delete merged branches
+    runs-on: ubuntu-latest
+
+    permissions:
+      contents: write
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Prune merged remote branches
+        run: |
+          git fetch --prune origin
+
+          MERGED=$(git branch -r --merged origin/integration \
+            | grep -vE 'origin/(integration|staging|HEAD|release/.+|gh-pages)' \
+            | sed 's|^\s*origin/||' \
+            | xargs)
+
+          if [ -z "$MERGED" ]; then
+            echo "Nothing to prune."
+            exit 0
+          fi
+
+          echo "Pruning: $MERGED"
+          for branch in $MERGED; do
+            git push origin --delete "$branch" && echo "  Deleted: $branch"
+          done

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

@@ -0,0 +1,94 @@
+name: Release
+
+on:
+  pull_request:
+    types: [closed]
+    branches:
+      - integration
+
+jobs:
+  test:
+    name: Test Suite
+    runs-on: ubuntu-latest
+    if: >-
+      github.event.pull_request.merged == true &&
+      startsWith(github.head_ref, 'release/')
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          version: "latest"
+
+      - name: Install dependencies
+        run: uv sync
+
+      - name: Lint
+        run: uv run ruff check .
+
+      - name: Unit tests
+        run: uv run pytest tests/ -v
+
+  build:
+    name: Build & GitHub Release
+    needs: test
+    runs-on: ubuntu-latest
+
+    permissions:
+      contents: write
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          version: "latest"
+
+      - name: Extract version
+        id: version
+        run: |
+          VERSION=$(grep 'version' pyproject.toml | head -1 | sed 's/.*"\(.*\)".*/\1/')
+          echo "version=$VERSION" >> "$GITHUB_OUTPUT"
+
+      - name: Build wheel and sdist
+        run: uv build
+
+      - name: Create GitHub Release
+        uses: softprops/action-gh-release@v2
+        with:
+          tag_name: v${{ steps.version.outputs.version }}
+          name: v${{ steps.version.outputs.version }}
+          generate_release_notes: true
+          files: dist/*
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+  publish:
+    name: Publish to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    if: vars.PUBLISH_TO_PYPI == 'true'
+
+    environment:
+      name: pypi
+      url: https://pypi.org/p/cutip-blocks
+
+    permissions:
+      id-token: write
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          version: "latest"
+
+      - name: Build
+        run: uv build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

cutip_blocks-0.1.0/.gitignore

@@ -0,0 +1,41 @@
+# ── Virtual Environments ──────────────────────────────────────────────────────
+.venv/
+venv/
+env/
+
+# ── Python ────────────────────────────────────────────────────────────────────
+__pycache__/
+*.py[cod]
+*.pyo
+*.pyd
+*.so
+*.egg
+*.egg-info/
+dist/
+build/
+.eggs/
+
+# ── Environment Files ─────────────────────────────────────────────────────────
+.env
+.env.*
+!.env.example
+
+# ── Testing & Coverage ────────────────────────────────────────────────────────
+.pytest_cache/
+.coverage
+coverage.xml
+htmlcov/
+
+# ── MkDocs ────────────────────────────────────────────────────────────────────
+site/
+
+# ── IDE & Editor ──────────────────────────────────────────────────────────────
+.vscode/
+.idea/
+*.swp
+*.swo
+.DS_Store
+
+# ── Claude Code ───────────────────────────────────────────────────────────────
+.claude/settings.local.json
+.claude/worktrees/

cutip_blocks-0.1.0/CLAUDE.md

@@ -0,0 +1,57 @@
+# CUTIP Blocks — Claude Working Context
+
+## What is CUTIP Blocks
+
+Reusable workflow blocks for CUTIP. Each block is a decorated Python function that maps to a single CLI operation (kubectl, ssh, cp, etc.). Blocks execute at runtime and provide metadata for cutip-desktop visualization.
+
+## Key Conventions
+
+- **Never auto-commit.** Only commit when explicitly asked.
+- **uv** is the package manager. Always `uv run`, `uv add`.
+- **Run tests**: `uv run pytest tests/ -v`
+- **Block naming**: `category.verb` — `k8s.get_secret`, `ssh.exec`, `file.copy`
+- **Each block function gets only the `@block` decorator** — no stacking
+- **SSH sessions use `sesh` parameter name** — never `conn`, `session`, `ssh`
+- **Logging**: every block logs its command via loguru with `[BlockName]` prefix
+- **Redaction**: passwords/tokens/keys are never logged — use `****`
+
+## Architecture
+
+```
+cutip_blocks/
+├── __init__.py          # Public API: block decorator, BlockRegistry
+├── decorator.py         # @block decorator + BlockMeta dataclass
+├── registry.py          # BlockRegistry — discovers all blocks
+└── blocks/              # Block implementations by category
+    ├── container.py     # start, stop, remove, exec, exec_stream
+    ├── ssh.py           # session, exec, probe (SSHSession with redaction)
+    ├── file.py          # copy, copy_tree, read_yaml, write_yaml, replace, is_empty
+    ├── k8s.py           # get_deployment, get_secret, get_pod, exec, cp, apply, patch_deployment, rollout_status
+    ├── download.py      # http_fetch
+    ├── config.py        # render_template, substitute_vars
+    ├── validate.py      # path_exists, env_var_set, ip_valid
+    ├── service.py       # poll_until_ready, wait_for_exit
+    └── crictl.py        # image_ls, image_rm, image_import
+```
+
+## Block Categories
+
+| Category | Tool | Examples |
+|----------|------|---------|
+| container | podman/docker | start, stop, remove, exec |
+| ssh | ssh/paramiko | session, exec, probe |
+| file | filesystem | copy, replace, is_empty |
+| k8s | kubectl | get_secret, get_pod, cp, apply |
+| crictl | crictl/ctr | image_ls, image_rm, image_import |
+| download | http | http_fetch |
+| config | templates | render_template |
+| validate | checks | path_exists, env_var_set |
+| service | daemons | poll_until_ready |
+
+## Branch Conventions
+
+Same as cutip — see cutip/CLAUDE.md.
+
+## Versioning
+
+Semantic versioning. Stays at 0.x until cutip-core reaches 1.0.

cutip_blocks-0.1.0/LICENSE

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

cutip_blocks-0.1.0/PKG-INFO

@@ -0,0 +1,107 @@
+Metadata-Version: 2.4
+Name: cutip-blocks
+Version: 0.1.0
+Summary: Reusable workflow blocks for CUTIP — container, SSH, k8s, file, and more
+Project-URL: Homepage, https://github.com/joshuajerome/cutip-blocks
+Project-URL: Repository, https://github.com/joshuajerome/cutip-blocks
+Project-URL: Bug Tracker, https://github.com/joshuajerome/cutip-blocks/issues
+Author: Joshua Jerome
+License: MIT
+License-File: LICENSE
+Keywords: blocks,containers,cutip,kubernetes,ssh,workflow
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.11
+Requires-Dist: cutip>=0.2.0
+Requires-Dist: loguru>=0.7
+Requires-Dist: paramiko>=3.0
+Requires-Dist: pyyaml>=6.0
+Provides-Extra: docs
+Requires-Dist: mkdocs-callouts>=1.14; extra == 'docs'
+Requires-Dist: mkdocs-material>=9.5; extra == 'docs'
+Requires-Dist: mkdocs<2.0; extra == 'docs'
+Description-Content-Type: text/markdown
+
+# cutip-blocks
+
+[![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-blue)](https://www.python.org/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE)
+[![cutip](https://img.shields.io/badge/cutip-%E2%89%A50.2.0-purple)](https://github.com/joshuajerome/cutip)
+
+Reusable workflow blocks for [CUTIP](https://github.com/joshuajerome/cutip) — Container Unit Templates in Python.
+
+Each block is a decorated Python function that maps to a single CLI operation (`kubectl`, `ssh`, `cp`, etc.). Blocks execute at runtime and provide metadata for [cutip-desktop](https://github.com/joshuajerome/cutip-desktop) DAG visualization.
+
+## Installation
+
+```bash
+pip install cutip-blocks
+```
+
+## Block Categories
+
+| Category | Blocks | Maps to |
+|----------|--------|---------|
+| **container** | `start`, `stop`, `remove`, `exec`, `exec_stream` | `podman`/`docker` |
+| **ssh** | `session`, `exec`, `probe` | `ssh`/`paramiko` |
+| **file** | `copy`, `copy_tree`, `read_yaml`, `write_yaml`, `read_json`, `write_json`, `replace`, `is_empty` | filesystem |
+| **k8s** | `get_deployment`, `get_secret`, `get_pod`, `exec`, `cp`, `apply`, `patch_deployment`, `rollout_status` | `kubectl` |
+| **crictl** | `image_ls`, `image_rm`, `image_import` | `crictl`/`ctr` |
+| **download** | `http_fetch` | HTTP GET |
+| **config** | `render_template`, `substitute_vars` | template rendering |
+| **validate** | `path_exists`, `env_var_set`, `ip_valid` | precondition checks |
+| **service** | `poll_until_ready`, `wait_for_exit` | readiness polling |
+
+## Usage
+
+```python
+from cutip.workflow import action, orchestrator, stage
+from cutip_blocks.blocks import container, ssh, k8s
+
+@action(name="Check Deployment")
+def check_deploy(ctx, sesh, ns, deploy):
+    k8s.get_deployment(ctx, sesh, namespace=ns, deployment=deploy)
+
+@orchestrator
+def main(ctx):
+    container.start(ctx, container="my-app")
+
+    with ssh.session(ctx, container="my-app",
+                     host="10.0.0.1", username="root",
+                     password=ctx.config["password"]) as sesh:
+
+        stage("Validation")
+        check_deploy(ctx, sesh, "default", "web")
+
+        stage("Operations")
+        k8s.apply(ctx, sesh, file="/tmp/patch.yaml")
+
+    container.stop(ctx, container="my-app")
+```
+
+## SSH Session
+
+All SSH-based blocks share a persistent connection via context manager. One SSH handshake, reused for all commands. Credentials are redacted in all log output.
+
+```
+INFO | [Get Deployment] ssh root@10.0.0.1 :: kubectl get deployment -n default web -o name
+INFO | [Get Secret] ssh root@10.0.0.1 :: kubectl get secret -n ns creds -o name
+```
+
+## Block Discovery
+
+```python
+from cutip_blocks import BlockRegistry
+
+registry = BlockRegistry.discover()
+for meta, fn in registry.blocks:
+    print(f"{meta.category}.{meta.action} — {meta.name}")
+```
+
+## License
+
+MIT

cutip_blocks-0.1.0/README.md

@@ -0,0 +1,79 @@
+# cutip-blocks
+
+[![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-blue)](https://www.python.org/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE)
+[![cutip](https://img.shields.io/badge/cutip-%E2%89%A50.2.0-purple)](https://github.com/joshuajerome/cutip)
+
+Reusable workflow blocks for [CUTIP](https://github.com/joshuajerome/cutip) — Container Unit Templates in Python.
+
+Each block is a decorated Python function that maps to a single CLI operation (`kubectl`, `ssh`, `cp`, etc.). Blocks execute at runtime and provide metadata for [cutip-desktop](https://github.com/joshuajerome/cutip-desktop) DAG visualization.
+
+## Installation
+
+```bash
+pip install cutip-blocks
+```
+
+## Block Categories
+
+| Category | Blocks | Maps to |
+|----------|--------|---------|
+| **container** | `start`, `stop`, `remove`, `exec`, `exec_stream` | `podman`/`docker` |
+| **ssh** | `session`, `exec`, `probe` | `ssh`/`paramiko` |
+| **file** | `copy`, `copy_tree`, `read_yaml`, `write_yaml`, `read_json`, `write_json`, `replace`, `is_empty` | filesystem |
+| **k8s** | `get_deployment`, `get_secret`, `get_pod`, `exec`, `cp`, `apply`, `patch_deployment`, `rollout_status` | `kubectl` |
+| **crictl** | `image_ls`, `image_rm`, `image_import` | `crictl`/`ctr` |
+| **download** | `http_fetch` | HTTP GET |
+| **config** | `render_template`, `substitute_vars` | template rendering |
+| **validate** | `path_exists`, `env_var_set`, `ip_valid` | precondition checks |
+| **service** | `poll_until_ready`, `wait_for_exit` | readiness polling |
+
+## Usage
+
+```python
+from cutip.workflow import action, orchestrator, stage
+from cutip_blocks.blocks import container, ssh, k8s
+
+@action(name="Check Deployment")
+def check_deploy(ctx, sesh, ns, deploy):
+    k8s.get_deployment(ctx, sesh, namespace=ns, deployment=deploy)
+
+@orchestrator
+def main(ctx):
+    container.start(ctx, container="my-app")
+
+    with ssh.session(ctx, container="my-app",
+                     host="10.0.0.1", username="root",
+                     password=ctx.config["password"]) as sesh:
+
+        stage("Validation")
+        check_deploy(ctx, sesh, "default", "web")
+
+        stage("Operations")
+        k8s.apply(ctx, sesh, file="/tmp/patch.yaml")
+
+    container.stop(ctx, container="my-app")
+```
+
+## SSH Session
+
+All SSH-based blocks share a persistent connection via context manager. One SSH handshake, reused for all commands. Credentials are redacted in all log output.
+
+```
+INFO | [Get Deployment] ssh root@10.0.0.1 :: kubectl get deployment -n default web -o name
+INFO | [Get Secret] ssh root@10.0.0.1 :: kubectl get secret -n ns creds -o name
+```
+
+## Block Discovery
+
+```python
+from cutip_blocks import BlockRegistry
+
+registry = BlockRegistry.discover()
+for meta, fn in registry.blocks:
+    print(f"{meta.category}.{meta.action} — {meta.name}")
+```
+
+## License
+
+MIT

cutip_blocks-0.1.0/cutip_blocks/__init__.py

@@ -0,0 +1,6 @@
+"""CUTIP Blocks — reusable workflow blocks for CUTIP."""
+
+from cutip_blocks.decorator import BlockMeta, block
+from cutip_blocks.registry import BlockRegistry
+
+__all__ = ["block", "BlockMeta", "BlockRegistry"]

cutip_blocks-0.1.0/cutip_blocks/blocks/__init__.py

@@ -0,0 +1 @@
+"""Block implementations by category."""

cutip_blocks-0.1.0/cutip_blocks/blocks/config.py

@@ -0,0 +1,53 @@
+"""Config blocks — template rendering and variable substitution."""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+from loguru import logger
+
+from cutip_blocks.decorator import block
+
+
+@block(name="Render Template", category="config", action="render_template")
+def render_template(
+    ctx,
+    *,
+    template: str | Path,
+    dest: str | Path,
+    variables: dict[str, str],
+) -> Path:
+    """Render a template file with {{ var }} substitution.
+
+    Args:
+        template: Path to template file.
+        dest: Path to write rendered output.
+        variables: Dict of variable name → value.
+    """
+    template, dest = Path(template), Path(dest)
+    logger.info("[Render Template] {} → {} ({} vars)", template, dest, len(variables))
+
+    text = template.read_text(encoding="utf-8")
+    for key, value in variables.items():
+        text = text.replace(f"{{{{ {key} }}}}", str(value))
+        text = text.replace(f"{{{{{key}}}}}", str(value))
+
+    dest.parent.mkdir(parents=True, exist_ok=True)
+    dest.write_text(text, encoding="utf-8")
+    return dest
+
+
+@block(name="Substitute Vars", category="config", action="substitute_vars")
+def substitute_vars(ctx, *, text: str, variables: dict[str, str]) -> str:
+    """Replace {{ var }} placeholders in a string.
+
+    Args:
+        text: Input string with placeholders.
+        variables: Dict of variable name → value.
+    """
+    result = text
+    for key, value in variables.items():
+        result = result.replace(f"{{{{ {key} }}}}", str(value))
+        result = result.replace(f"{{{{{key}}}}}", str(value))
+    return result