click-clop 0.3.0__tar.gz

click_clop-0.3.0/.gitignore

@@ -0,0 +1,34 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+
+# Type checking
+.mypy_cache/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Local config
+config.local.toml
+
+# Claude Code worktrees
+.claude/worktrees/

click_clop-0.3.0/.python-version

@@ -0,0 +1 @@
+3.14

click_clop-0.3.0/CLAUDE.md

@@ -0,0 +1,79 @@
+# click-clop — Claude Code Guidelines
+
+## Project Overview
+
+click-clop is a **framework + scaffold** for Python CLI applications.
+It's both a pip-installable library and a project generator (`click-clop new <name>`).
+
+Every feature in a generated project is simultaneously a CLI command (Click),
+MCP tool (FastMCP), and REST endpoint (FastAPI) via the service-layer pattern.
+
+## Architecture
+
+```
+┌── click-clop (this project) ──────────────────┐
+│                                                │
+│  Library (pip install click-clop):             │
+│    service.py   — Service base + registry      │
+│    expose.py    — CLI/MCP/REST auto-wrappers   │
+│    config.py    — TOML config loading          │
+│    secrets.py   — 1Password CRUD               │
+│    telemetry.py — OpenTelemetry + Alloy        │
+│    logging.py   — structlog setup              │
+│    system_detect.py — env detection            │
+│                                                │
+│  Scaffold (click-clop new):                    │
+│    cli.py       — CLI entry point              │
+│    scaffold.py  — Copier wrapper               │
+│    template/    — Copier template files         │
+└────────────────────────────────────────────────┘
+```
+
+## Directory Structure
+
+```
+src/click_clop/
+├── __init__.py         # Public API
+├── cli.py              # click-clop CLI (new, detect)
+├── scaffold.py         # Project generation
+├── service.py          # Service pattern
+├── expose.py           # Auto-exposure wrappers
+├── config.py           # TOML config
+├── secrets.py          # 1Password
+├── telemetry.py        # OpenTelemetry
+├── logging.py          # structlog
+├── system_detect.py    # System probing
+└── template/           # Copier template (generated projects)
+    ├── copier.yml
+    ├── src/{{module_name}}/
+    ├── tests/
+    ├── features/
+    ├── helm/
+    ├── docs/
+    ├── alloy/
+    ├── Makefile.jinja
+    ├── Dockerfile.jinja
+    ├── CLAUDE.md.jinja
+    └── ...
+```
+
+## Development
+
+| Task | Command |
+|------|---------|
+| Install | `make install-dev` |
+| Test | `make test` |
+| Lint | `make lint` |
+| Format | `make format` |
+| Build | `make build` |
+
+## Agent Rules
+
+When implementing changes to click-clop itself:
+
+1. **Use worktrees**: Use Claude Code's built-in `EnterWorktree` to work in isolation
+2. **Leave changes unstaged** for review
+3. **Service pattern**: core logic in service.py, thin wrappers in expose.py
+4. **Template changes**: update both the template files AND the self-hosting equivalents
+5. **Write tests**: `tests/unit/` for library code
+6. **Conventional commits**: `feat:`, `fix:`, `docs:`, etc.

click_clop-0.3.0/Makefile

@@ -0,0 +1,73 @@
+# click-clop — Framework and scaffold for Python CLI applications
+# This is click-clop's own Makefile (the framework project itself).
+
+CONTAINER_RUNTIME ?= $(shell command -v podman 2>/dev/null || echo docker)
+IMAGE_NAME ?= click-clop
+IMAGE_TAG ?= latest
+PYTEST ?= uv run pytest
+BEHAVE ?= uv run behave
+
+.DEFAULT_GOAL := help
+
+.PHONY: help
+help: ## Show this help message
+	@grep -E '^[a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) | sort | \
+		awk 'BEGIN {FS = ":.*?## "}; {printf "\033[36m%-20s\033[0m %s\n", $$1, $$2}'
+
+# ── Python / uv ──────────────────────────────────────────────
+
+.PHONY: install
+install: ## Install project dependencies
+	uv sync
+
+.PHONY: install-dev
+install-dev: ## Install with dev dependencies
+	uv sync --all-extras
+
+.PHONY: lint
+lint: ## Run linting (ruff + mypy)
+	uv run ruff check src/ tests/
+	uv run mypy src/
+
+.PHONY: format
+format: ## Format code with ruff
+	uv run ruff format src/ tests/
+	uv run ruff check --fix src/ tests/
+
+.PHONY: test
+test: ## Run all tests
+	$(PYTEST) tests/ -v
+
+.PHONY: test-unit
+test-unit: ## Run unit tests only
+	$(PYTEST) tests/unit -v
+
+.PHONY: test-bdd
+test-bdd: ## Run BDD/Gherkin feature tests
+	$(BEHAVE) features/
+
+.PHONY: test-all
+test-all: test test-bdd ## Run unit + BDD tests
+
+.PHONY: coverage
+coverage: ## Generate test coverage report
+	$(PYTEST) tests/ --cov=src/click_clop --cov-report=html --cov-report=term
+
+# ── Container ────────────────────────────────────────────────
+
+.PHONY: build-image
+build-image: ## Build container image
+	$(CONTAINER_RUNTIME) build -t $(IMAGE_NAME):$(IMAGE_TAG) .
+
+# ── Cleanup ──────────────────────────────────────────────────
+
+.PHONY: clean
+clean: ## Clean build artifacts
+	find . -type d -name __pycache__ -exec rm -rf {} + 2>/dev/null || true
+	find . -type d -name .pytest_cache -exec rm -rf {} + 2>/dev/null || true
+	find . -type d -name .mypy_cache -exec rm -rf {} + 2>/dev/null || true
+	rm -rf build/ dist/ *.egg-info .coverage htmlcov/
+
+.PHONY: build
+build: clean ## Build distribution package
+	uv build

click_clop-0.3.0/PKG-INFO

@@ -0,0 +1,278 @@
+Metadata-Version: 2.4
+Name: click-clop
+Version: 0.3.0
+Summary: A reusable framework and scaffold for Python CLI applications with MCP, REST, and service-layer architecture
+Author: bpayne
+License: MIT
+Keywords: cli,click,framework,mcp,scaffold
+Requires-Python: >=3.14
+Requires-Dist: click>=8.1.0
+Requires-Dist: copier>=9.0.0
+Requires-Dist: fastapi>=0.115.0
+Requires-Dist: fastmcp>=2.0.0
+Requires-Dist: opentelemetry-api>=1.20.0
+Requires-Dist: opentelemetry-exporter-otlp>=1.20.0
+Requires-Dist: opentelemetry-sdk>=1.20.0
+Requires-Dist: questionary>=2.0.0
+Requires-Dist: rich>=13.0.0
+Requires-Dist: structlog>=24.0.0
+Requires-Dist: tomli>=2.0.0; python_version < '3.11'
+Requires-Dist: uvicorn>=0.34.0
+Provides-Extra: dev
+Requires-Dist: behave>=1.2.6; extra == 'dev'
+Requires-Dist: httpx>=0.27.0; extra == 'dev'
+Requires-Dist: mypy>=1.0; extra == 'dev'
+Requires-Dist: pytest-bdd>=7.0; extra == 'dev'
+Requires-Dist: pytest-cov>=5.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.8.0; extra == 'dev'
+Requires-Dist: sphinx-click>=6.0; extra == 'dev'
+Requires-Dist: sphinx-rtd-theme>=2.0; extra == 'dev'
+Requires-Dist: sphinx>=7.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# click-clop
+
+A Python framework and project generator where every feature is simultaneously a **CLI command** (Click), **MCP tool** (FastMCP), and **REST endpoint** (FastAPI).
+
+Write your business logic once as a service class — click-clop exposes it everywhere.
+
+```
+Service method  ──►  CLI command  (Click)
+                ──►  MCP tool     (FastMCP)
+                ──►  REST endpoint (FastAPI)
+```
+
+## Quick Start
+
+### Install
+
+```bash
+pip install click-clop
+```
+
+### Generate a new project
+
+```bash
+click-clop new my-app --description "My awesome CLI"
+cd my-app
+make install-dev
+```
+
+This scaffolds a complete project with a Makefile, Dockerfile, Helm charts, telemetry config, BDD tests, and documentation — with intelligent defaults based on your system.
+
+### Write a service
+
+```python
+# src/my_app/services/greet.py
+from click_clop import Service
+
+class GreetService(Service):
+    """Greeting service."""
+
+    name = "greet"
+    description = "Say hello"
+
+    def hello(self, name: str = "world") -> str:
+        """Say hello to someone."""
+        return f"Hello, {name}!"
+
+    def farewell(self, name: str = "world") -> str:
+        """Say goodbye to someone."""
+        return f"Goodbye, {name}!"
+
+_service = GreetService()  # auto-registers
+```
+
+### Expose as CLI
+
+```python
+import click
+from click_clop import expose_cli
+
+@click.group()
+def main():
+    """My CLI app."""
+
+expose_cli(main)  # all registered services become subcommands
+```
+
+```bash
+$ my-app greet hello --name Claude
+Hello, Claude!
+```
+
+### Expose as REST
+
+```python
+from click_clop import expose_rest
+
+app = expose_rest()  # creates /api/greet/hello, /api/greet/farewell
+```
+
+### Expose as MCP tools
+
+```python
+from fastmcp import FastMCP
+from click_clop import expose_mcp
+
+mcp = FastMCP("my-service")
+expose_mcp(mcp)  # registers greet_hello, greet_farewell tools
+```
+
+## CLI
+
+```
+click-clop new <PROJECT_NAME>   Create a new project from template
+  -d, --description TEXT         Project description
+  -a, --author TEXT              Author name (auto-detected from git)
+  -o, --output-dir PATH          Parent directory (default: cwd)
+
+click-clop detect                Show detected system capabilities
+```
+
+## Library API
+
+```python
+from click_clop import (
+    Service,            # Base class for services
+    ServiceRegistry,    # Global registry of all services
+    load_config,        # Load TOML config with env overrides
+    expose_cli,         # Add services to a Click group
+    expose_mcp,         # Add services as MCP tools
+    expose_rest,        # Add services as FastAPI endpoints
+)
+```
+
+### Configuration
+
+`load_config()` merges TOML files in order (later wins):
+
+1. `config.toml` — base defaults
+2. `config.dev.toml` — development overrides
+3. `config.local.toml` — local/gitignored overrides
+4. Environment variables with prefix
+
+```python
+from click_clop import load_config
+
+config = load_config(prefix="APP")
+```
+
+Environment variables map with double-underscore nesting:
+
+```
+APP_SERVER__HOST=0.0.0.0  →  config["server"]["host"]
+APP_DATABASE__PORT=5432   →  config["database"]["port"]
+```
+
+### Secrets (1Password)
+
+```python
+from click_clop.secrets import get_secret_field, ensure_secret
+
+# Read a secret
+api_key = get_secret_field("vault-name", "item-name", "api_key")
+
+# Create or update a secret
+ensure_secret("vault-name", "item-name", {"api_key": "sk-..."})
+```
+
+Requires the 1Password CLI (`op`) installed and authenticated.
+
+### Telemetry (OpenTelemetry)
+
+```python
+from click_clop.telemetry import setup_telemetry, get_tracer
+
+setup_telemetry(service_name="my-service", otlp_endpoint="http://localhost:4317")
+
+tracer = get_tracer("my_module")
+with tracer.start_as_current_span("operation"):
+    ...
+```
+
+### Logging (structlog)
+
+```python
+from click_clop.logging import setup_logging, get_logger
+
+setup_logging(level="INFO", json_output=True, service_name="my-service")
+log = get_logger("my_module")
+log.info("event", key="value")
+```
+
+### System Detection
+
+```python
+from click_clop.system_detect import detect_system
+
+info = detect_system()
+print(info.summary())
+```
+
+Detects Docker/Podman, Helm, 1Password CLI, Python, uv, Git, OS, and architecture.
+
+## Generated Project Structure
+
+```
+my_app/
+├── src/my_app/
+│   ├── __main__.py          # Entry point
+│   ├── cli.py               # CLI main group
+│   ├── server.py            # MCP + REST server
+│   └── services/
+│       └── hello.py         # Example service
+├── tests/
+│   └── unit/
+│       └── test_hello.py
+├── features/                # BDD/Gherkin tests
+├── helm/my_app/             # Kubernetes Helm charts
+├── alloy/config.alloy       # Grafana Alloy telemetry config
+├── docs/                    # Sphinx documentation
+├── config.toml              # Application config
+├── Makefile                 # Development tasks
+├── Dockerfile
+└── pyproject.toml
+```
+
+### Generated project commands
+
+```bash
+make install-dev    # Install with dev dependencies
+make test           # Run pytest
+make test-bdd       # Run BDD tests
+make lint           # Lint with ruff + mypy
+make format         # Format with ruff
+make serve          # Run REST + MCP server (Swagger at localhost:8000/docs)
+make build-image    # Build container image
+make helm-install   # Deploy via Helm
+make docs           # Build Sphinx docs
+```
+
+## Development
+
+```bash
+git clone https://github.com/bpayne/click-clop.git
+cd click-clop
+make install-dev
+make test
+make lint
+```
+
+## Type Mapping
+
+Service method parameters are automatically mapped:
+
+| Python type | CLI (Click) | REST (FastAPI) |
+|-------------|-------------|----------------|
+| `str` | `STRING` | `str` |
+| `int` | `INT` | `int` |
+| `float` | `FLOAT` | `float` |
+| `bool` | `--flag/--no-flag` | `bool` |
+
+Parameters without type annotations default to `str`.
+
+## License
+
+MIT

click_clop-0.3.0/PLAN.md

@@ -0,0 +1,179 @@
+# click-clop Implementation Plan
+
+## Architecture
+
+click-clop is **both** a library and a scaffold generator:
+
+1. **`click-clop` library** — pip-installable framework providing the service-layer pattern,
+   decorators, and utilities for building CLI+MCP+REST apps
+2. **`click-clop new <name>` CLI** — scaffolds a new project that depends on click-clop
+
+### Service Layer Pattern
+
+```
+┌─────────┐  ┌──────────┐  ┌──────────────┐
+│ Click   │  │ FastMCP  │  │ FastAPI/REST │
+│ CLI     │  │ Server   │  │ Endpoints    │
+└────┬────┘  └────┬─────┘  └──────┬───────┘
+     │            │               │
+     └────────────┼───────────────┘
+                  │
+          ┌───────▼───────┐
+          │ Service Layer  │  ← Core business logic lives here
+          │ (plain funcs)  │
+          └───────┬───────┘
+                  │
+          ┌───────▼───────┐
+          │   Config /     │
+          │   Telemetry /  │
+          │   Secrets      │
+          └───────────────┘
+```
+
+## Directory Structure (click-clop itself)
+
+```
+click-clop/
+├── src/
+│   └── click_clop/
+│       ├── __init__.py              # Public API exports
+│       ├── __main__.py              # python -m click_clop
+│       ├── cli.py                   # click-clop CLI (new, version, etc.)
+│       ├── scaffold.py              # Project generation logic
+│       ├── service.py               # ServiceBase class & registration
+│       ├── expose.py                # Thin wrapper generators (cli/mcp/rest)
+│       ├── config.py                # TOML config loading
+│       ├── secrets.py               # 1Password integration (read, create, update items)
+│       ├── system_detect.py         # Detect system capabilities (docker/podman, etc.)
+│       ├── telemetry.py             # OpenTelemetry + Alloy setup
+│       ├── logging.py               # Structured logging
+│       └── template/                # Copier template (the scaffold)
+│           ├── copier.yml           # Copier config + wizard questions
+│           ├── {{project_name}}/
+│           │   ├── src/
+│           │   │   └── {{module_name}}/
+│           │   │       ├── __init__.py.jinja
+│           │   │       ├── __main__.py.jinja
+│           │   │       ├── cli.py.jinja
+│           │   │       ├── server.py.jinja        # MCP + REST server
+│           │   │       ├── services/
+│           │   │       │   ├── __init__.py.jinja
+│           │   │       │   └── hello.py.jinja      # Example service
+│           │   │       ├── config.py.jinja
+│           │   │       └── secrets.py.jinja        # 1Password item CRUD helpers
+│           │   ├── tests/
+│           │   │   ├── conftest.py.jinja
+│           │   │   └── unit/
+│           │   │       └── test_hello.py.jinja
+│           │   ├── features/
+│           │   │   ├── steps/
+│           │   │   │   └── hello_steps.py.jinja
+│           │   │   └── hello.feature.jinja
+│           │   ├── docs/
+│           │   │   ├── conf.py.jinja
+│           │   │   ├── index.rst.jinja
+│           │   │   └── Makefile.jinja
+│           │   ├── helm/
+│           │   │   └── {{project_name}}/
+│           │   │       ├── Chart.yaml.jinja
+│           │   │       ├── values.yaml.jinja
+│           │   │       └── templates/
+│           │   │           ├── deployment.yaml.jinja
+│           │   │           ├── service.yaml.jinja
+│           │   │           ├── configmap.yaml.jinja
+│           │   │           ├── onepassworditem.yaml.jinja  # 1Password CRD
+│           │   │           └── NOTES.txt.jinja
+│           │   ├── .git-hooks/
+│           │   │   ├── pre-commit
+│           │   │   └── commit-msg
+│           │   ├── .git-templates/
+│           │   │   └── commit-message.txt
+│           │   ├── alloy/
+│           │   │   └── config.alloy.jinja
+│           │   ├── CLAUDE.md.jinja
+│           │   ├── .claude/
+│           │   │   └── settings.json.jinja
+│           │   ├── Makefile.jinja
+│           │   ├── Dockerfile.jinja
+│           │   ├── pyproject.toml.jinja
+│           │   ├── config.toml.jinja
+│           │   ├── config.dev.toml.jinja
+│           │   ├── .gitignore.jinja
+│           │   ├── .python-version.jinja
+│           │   └── README.md.jinja
+├── tests/
+│   ├── conftest.py
+│   └── unit/
+│       ├── test_service.py
+│       ├── test_config.py
+│       └── test_scaffold.py
+├── features/
+│   ├── steps/
+│   │   └── scaffold_steps.py
+│   └── scaffold.feature
+├── docs/
+│   └── conf.py
+├── CLAUDE.md
+├── Makefile
+├── Dockerfile
+├── pyproject.toml
+├── .gitignore
+└── .python-version
+```
+
+## Implementation Steps
+
+### Phase 1: Core Library
+1. Set up src/ layout, pyproject.toml with all dependencies
+2. Implement `ServiceBase` — register plain functions, autodiscover services
+3. Implement `expose.py` — generate Click commands, FastMCP tools, FastAPI routes from services
+4. Implement `config.py` — TOML config loading with env overlay
+5. Implement `secrets.py` — 1Password integration (read, create, update, delete items via `op` CLI)
+6. Implement `telemetry.py` — OpenTelemetry SDK + OTLP export (Alloy-compatible)
+7. Implement `logging.py` — structlog with JSON output
+8. Implement `system_detect.py` — auto-detect system capabilities:
+   - Container runtime: `docker` vs `podman` (check which is available, prefer podman)
+   - Helm availability and version
+   - 1Password CLI (`op`) availability
+   - Python version, uv version
+   - Git version and config
+   - Available shell (bash/zsh)
+   - OS/platform info
+
+### Phase 2: Scaffold Generator
+9. Create copier template with minimal wizard (name, description, author)
+   - Wizard auto-detects and pre-fills: container runtime, python version, author from git config
+   - User confirms or overrides detected values
+10. Implement `click-clop new` CLI command (wraps copier + system detection)
+11. Template: Makefile with uv/docker/helm proxies
+    - Uses detected container runtime (`docker` or `podman`) as variable
+12. Template: Dockerfile (multi-stage, uv-based)
+13. Template: Helm chart
+    - Includes `OnePasswordItem` CRD resources for secret injection
+    - Chart.yaml declares 1password-connect dependency
+    - values.yaml has `onepassword.vault` and `onepassword.items[]` config
+14. Template: git hooks (pre-commit: lint+test, commit-msg: conventional commits)
+15. Template: git commit message template
+16. Template: CLAUDE.md + .claude/settings.json with agent rules
+17. Template: Sphinx docs with autodoc
+18. Template: Grafana Alloy config
+    - OTLP receiver for traces/metrics/logs from the app
+    - Prometheus remote-write export
+    - Loki log export
+    - Tempo trace export
+    - Configurable endpoints via config.toml
+19. Template: Gherkin feature file + behave steps
+20. Template: Swagger UI via FastAPI
+21. Template: config.toml + config.dev.toml
+22. Template: pyproject.toml with all tasks
+23. Template: .gitignore, .python-version, README.md
+24. Template: secrets.py — helper module for 1Password item CRUD in generated projects
+    - `create_secret(vault, title, fields)` — create a new 1Password item
+    - `get_secret(vault, title)` — read an item
+    - `update_secret(vault, title, fields)` — update fields
+    - `ensure_secret(vault, title, fields)` — idempotent create-or-update
+    - Exposed as CLI commands, MCP tools, and REST endpoints via the service layer
+
+### Phase 3: Self-hosting
+25. click-clop's own Makefile, Dockerfile, CLAUDE.md, tests
+26. Verify `click-clop new testapp` generates a working project