stapel-tools 0.3.1__tar.gz

stapel_tools-0.3.1/PKG-INFO

@@ -0,0 +1,112 @@
+Metadata-Version: 2.4
+Name: stapel-tools
+Version: 0.3.1
+Summary: CLI scaffold and linting tools for Stapel/Django microservices
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+
+# stapel-tools
+
+CLI scaffold and linting tools for Stapel/Django projects.
+
+## Install
+
+```bash
+pip install git+https://github.com/usestapel/stapel-tools.git
+```
+
+Or as a dev dependency in your project:
+
+```bash
+pip install -e path/to/stapel-tools
+```
+
+## Commands
+
+### `stapel-create-project` — interactive project wizard
+
+```bash
+stapel-create-project                          # full wizard
+stapel-create-project my-app --type monolith   # skip some wizard steps
+stapel-create-project my-app \
+    --type monolith \
+    --title "My App" \
+    --url https://myapp.com \
+    --company-name "ACME" \
+    --company-email hello@myapp.com \
+    --modules auth billing              # fully non-interactive
+```
+
+Project types: `monolith` (recommended), `microservices`, `minimal` (no Docker, SQLite).
+
+### `stapel-new-service` — add a service to an existing project
+
+```bash
+stapel-new-service auth
+stapel-new-service auth --title "Auth Service" --prefix iron-
+stapel-new-service blog --celery
+stapel-new-service blog --dry-run
+```
+
+### `stapel-new-library` — scaffold a standalone stapel-* package repo
+
+For contributing a new reusable package to the framework (or building your
+own to the same standard). Materializes the Stapel library standard: flat
+layout, `STAPEL_<NAME>` settings namespace, comm surface with JSON schemas,
+serializer seams, MODULE.md, community files, CI with the codecov
+ratchet/floor policy, ruff git hooks. The generated repo's own test suite
+is green out of the box.
+
+```bash
+stapel-new-library search                                 # L2 service module
+stapel-new-library attributes --kind library              # L1 importable lib
+stapel-new-library support-chat --title "Support chat" --dir ~/Projects
+```
+
+Kinds: `module` (default — Django app with models/views/comm surface;
+modules never import each other) and `library` (importable package without
+service identity, like stapel-attributes).
+
+### `stapel-new-module` — add a Django app to a service
+
+```bash
+cd svc-auth/
+stapel-new-module users
+stapel-new-module billing --title "Billing Plans"
+```
+
+### `stapel-remove-service` — remove a service
+
+```bash
+stapel-remove-service auth
+stapel-remove-service auth --prefix iron- --yes
+stapel-remove-service auth --dry-run
+```
+
+### `stapel-lint` — project-specific static linter
+
+```bash
+stapel-lint                        # scan current directory
+stapel-lint svc-auth/              # scan specific service
+stapel-lint --stats                # show per-rule counts
+stapel-lint --ignore R002          # skip a rule
+```
+
+Rules: R001 bare `Response()`, R002 `serializers.ValidationError`, R003 undocumented `@action`,
+R004 `@dataclass` without docstring, R005 hardcoded error string, R006 `StapelResponse(dict)`.
+
+Suppress per-line: `# noqa: R001`
+
+## Available modules
+
+| Module | Description |
+|--------|-------------|
+| `core` | Core framework (always included) |
+| `auth` | Authentication — JWT, OAuth, OTP |
+| `billing` | Billing & subscriptions |
+| `cdn` | File uploads & CDN |
+| `notifications` | Email / push notifications |
+| `profiles` | User profiles |
+| `translate` | Translations & i18n |
+| `workspaces` | Workspaces & multi-tenancy |
+| `gdpr` | GDPR — data export & deletion |

stapel_tools-0.3.1/README.md

@@ -0,0 +1,105 @@
+# stapel-tools
+
+CLI scaffold and linting tools for Stapel/Django projects.
+
+## Install
+
+```bash
+pip install git+https://github.com/usestapel/stapel-tools.git
+```
+
+Or as a dev dependency in your project:
+
+```bash
+pip install -e path/to/stapel-tools
+```
+
+## Commands
+
+### `stapel-create-project` — interactive project wizard
+
+```bash
+stapel-create-project                          # full wizard
+stapel-create-project my-app --type monolith   # skip some wizard steps
+stapel-create-project my-app \
+    --type monolith \
+    --title "My App" \
+    --url https://myapp.com \
+    --company-name "ACME" \
+    --company-email hello@myapp.com \
+    --modules auth billing              # fully non-interactive
+```
+
+Project types: `monolith` (recommended), `microservices`, `minimal` (no Docker, SQLite).
+
+### `stapel-new-service` — add a service to an existing project
+
+```bash
+stapel-new-service auth
+stapel-new-service auth --title "Auth Service" --prefix iron-
+stapel-new-service blog --celery
+stapel-new-service blog --dry-run
+```
+
+### `stapel-new-library` — scaffold a standalone stapel-* package repo
+
+For contributing a new reusable package to the framework (or building your
+own to the same standard). Materializes the Stapel library standard: flat
+layout, `STAPEL_<NAME>` settings namespace, comm surface with JSON schemas,
+serializer seams, MODULE.md, community files, CI with the codecov
+ratchet/floor policy, ruff git hooks. The generated repo's own test suite
+is green out of the box.
+
+```bash
+stapel-new-library search                                 # L2 service module
+stapel-new-library attributes --kind library              # L1 importable lib
+stapel-new-library support-chat --title "Support chat" --dir ~/Projects
+```
+
+Kinds: `module` (default — Django app with models/views/comm surface;
+modules never import each other) and `library` (importable package without
+service identity, like stapel-attributes).
+
+### `stapel-new-module` — add a Django app to a service
+
+```bash
+cd svc-auth/
+stapel-new-module users
+stapel-new-module billing --title "Billing Plans"
+```
+
+### `stapel-remove-service` — remove a service
+
+```bash
+stapel-remove-service auth
+stapel-remove-service auth --prefix iron- --yes
+stapel-remove-service auth --dry-run
+```
+
+### `stapel-lint` — project-specific static linter
+
+```bash
+stapel-lint                        # scan current directory
+stapel-lint svc-auth/              # scan specific service
+stapel-lint --stats                # show per-rule counts
+stapel-lint --ignore R002          # skip a rule
+```
+
+Rules: R001 bare `Response()`, R002 `serializers.ValidationError`, R003 undocumented `@action`,
+R004 `@dataclass` without docstring, R005 hardcoded error string, R006 `StapelResponse(dict)`.
+
+Suppress per-line: `# noqa: R001`
+
+## Available modules
+
+| Module | Description |
+|--------|-------------|
+| `core` | Core framework (always included) |
+| `auth` | Authentication — JWT, OAuth, OTP |
+| `billing` | Billing & subscriptions |
+| `cdn` | File uploads & CDN |
+| `notifications` | Email / push notifications |
+| `profiles` | User profiles |
+| `translate` | Translations & i18n |
+| `workspaces` | Workspaces & multi-tenancy |
+| `gdpr` | GDPR — data export & deletion |

stapel_tools-0.3.1/pyproject.toml

@@ -0,0 +1,31 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "stapel-tools"
+version = "0.3.1"
+description = "CLI scaffold and linting tools for Stapel/Django microservices"
+readme = "README.md"
+requires-python = ">=3.11"
+dependencies = []
+
+[project.scripts]
+stapel-lint = "stapel_tools.lint:main"
+stapel-new-service = "stapel_tools.new_service:main"
+stapel-new-module = "stapel_tools.new_module:main"
+stapel-new-library = "stapel_tools.new_library:main"
+stapel-remove-service = "stapel_tools.remove_service:main"
+stapel-create-project = "stapel_tools.create_project:main"
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["stapel_tools*"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py311"
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I"]
+ignore = ["E501"]

stapel_tools-0.3.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

stapel_tools-0.3.1/stapel_tools/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

stapel_tools-0.3.1/stapel_tools/_compose_templates.py

@@ -0,0 +1,373 @@
+"""Docker Compose templates for project scaffolding."""
+
+# Runs on EVERY postgres startup (via the db service's command wrapper),
+# creating any database listed in POSTGRES_MULTIPLE_DATABASES that does not
+# exist yet. Running at every startup — not just first initdb — means adding
+# a service later creates its database without wiping the data volume.
+POSTGRES_ENSURE_DATABASES = """\
+#!/bin/sh
+set -eu
+
+ensure_database_exists() {
+    database=$1
+    if psql -v ON_ERROR_STOP=1 -d postgres --username "$POSTGRES_USER" -lqt \\
+        | cut -d '|' -f 1 | grep -qw "$database"; then
+        echo "  database '$database' exists"
+    else
+        echo "  creating database '$database'"
+        psql -v ON_ERROR_STOP=1 -d postgres --username "$POSTGRES_USER" <<-EOSQL
+            CREATE DATABASE $database;
+            GRANT ALL PRIVILEGES ON DATABASE $database TO $POSTGRES_USER;
+EOSQL
+    fi
+}
+
+if [ -n "${POSTGRES_MULTIPLE_DATABASES:-}" ]; then
+    echo "Ensuring databases exist: $POSTGRES_MULTIPLE_DATABASES"
+    for db in $(echo "$POSTGRES_MULTIPLE_DATABASES" | tr ',' ' '); do
+        db=$(echo "$db" | xargs)
+        [ -n "$db" ] && ensure_database_exists "$db"
+    done
+fi
+"""
+
+# Mounted at /etc/nginx/conf.d/nginx.conf. stapel-new-service appends a
+# location block per service before the closing brace.
+NGINX_CONF = """\
+server {
+    listen 80;
+    server_name _;
+    client_max_body_size 50m;
+    resolver 127.0.0.11 valid=10s;
+
+    location /staticfiles/ {
+        alias /staticfiles/;
+    }
+
+    location /media/ {
+        alias /media/;
+    }
+}
+"""
+
+
+# ─── Broker building blocks ─────────────────────────────────────────────────
+# Compose bases carry {{BROKER_SERVICES}} / {{BROKER_VOLUMES}} markers; the
+# generator splices the chosen broker(s) in. Env templates carry
+# {{BROKER_ENV}}. A dedicated Task broker (--task-broker) adds its blocks
+# next to the event broker's.
+
+NATS_SERVICE_BLOCK = """\
+  # Events (JetStream) + RPC (request-reply) for stapel_core.comm
+  nats:
+    image: nats:2.10-alpine
+    restart: unless-stopped
+    command: ["--jetstream", "--store_dir", "/data"]
+    volumes:
+      - nats-data:/data
+
+"""
+
+KAFKA_SERVICE_BLOCK = """\
+  kafka:
+    image: apache/kafka:3.9.0
+    restart: unless-stopped
+    environment:
+      KAFKA_NODE_ID: 1
+      KAFKA_PROCESS_ROLES: broker,controller
+      KAFKA_LISTENERS: PLAINTEXT://:9092,CONTROLLER://:9093
+      KAFKA_ADVERTISED_LISTENERS: PLAINTEXT://kafka:9092
+      KAFKA_CONTROLLER_QUORUM_VOTERS: 1@kafka:9093
+      KAFKA_CONTROLLER_LISTENER_NAMES: CONTROLLER
+      KAFKA_OFFSETS_TOPIC_REPLICATION_FACTOR: 1
+      KAFKA_AUTO_CREATE_TOPICS_ENABLE: "true"
+    volumes:
+      - kafka-data:/var/lib/kafka/data
+
+"""
+
+NATS_ENV_BLOCK = """\
+# ─── NATS: events (JetStream) + RPC ─────────────────────────────────────────
+STAPEL_BUS_BACKEND=nats
+NATS_URL=nats://nats:4222
+"""
+
+KAFKA_ENV_BLOCK = """\
+# ─── Kafka: events ──────────────────────────────────────────────────────────
+STAPEL_BUS_BACKEND=kafka
+KAFKA_BOOTSTRAP_SERVERS=kafka:9092
+"""
+
+# Task broker only (monolith --task-broker nats): Actions stay in-process;
+# STAPEL_TASK_DISPATCH=bus makes stapel_core publish task.* events through
+# the broker to a dedicated worker (STAPEL_COMM["TASK_DISPATCH"]).
+TASK_ONLY_NATS_ENV_BLOCK = """\
+# ─── NATS: broker for long-running Tasks only (Actions stay in-process) ────
+STAPEL_BUS_BACKEND=nats
+NATS_URL=nats://nats:4222
+STAPEL_TASK_DISPATCH=bus
+"""
+
+_BROKER_SERVICES = {"nats": NATS_SERVICE_BLOCK, "kafka": KAFKA_SERVICE_BLOCK, "none": ""}
+_BROKER_VOLUMES = {"nats": "  nats-data:\n", "kafka": "  kafka-data:\n", "none": ""}
+_BROKER_ENV = {"nats": NATS_ENV_BLOCK, "kafka": KAFKA_ENV_BLOCK, "none": ""}
+_BROKER_URL_LINES = {
+    "nats": "NATS_URL=nats://nats:4222\n",
+    "kafka": "KAFKA_BOOTSTRAP_SERVERS=kafka:9092\n",
+}
+
+
+def render_compose_base(template: str, broker: str, task_broker: str = "none") -> str:
+    """Splice the chosen broker(s) (nats | kafka | none) into a compose base.
+
+    *task_broker* adds a second broker dedicated to Tasks when it differs
+    from the event broker.
+    """
+    brokers = [b for b in ("nats", "kafka") if b in (broker, task_broker)]
+    services = "".join(_BROKER_SERVICES[b] for b in brokers)
+    volumes = "".join(_BROKER_VOLUMES[b] for b in brokers)
+    return template.replace("{{BROKER_SERVICES}}", services).replace(
+        "{{BROKER_VOLUMES}}", volumes
+    )
+
+
+def _broker_env(broker: str, task_broker: str) -> str:
+    if task_broker in ("none", broker):
+        return _BROKER_ENV[broker]
+    if broker == "none":
+        # Broker exists for Tasks only — Actions stay in-process.
+        return TASK_ONLY_NATS_ENV_BLOCK
+    # Two brokers: RoutingBus splits by topic prefix — task.* to the task
+    # broker, everything else to the event broker.
+    urls = "".join(
+        _BROKER_URL_LINES[b] for b in ("nats", "kafka") if b in (broker, task_broker)
+    )
+    return (
+        f"# ─── Brokers: {broker} for events/RPC, {task_broker} for Tasks ─────────────────\n"
+        "STAPEL_BUS_BACKEND=routing\n"
+        f'STAPEL_BUS_ROUTES={{"task.": "{task_broker}", "": "{broker}"}}\n'
+        f"{urls}"
+    )
+
+
+def render_env(template: str, broker: str, ctx: dict, task_broker: str = "none") -> str:
+    # Format first ({{BROKER_ENV}} collapses to {BROKER_ENV}), then splice the
+    # broker block in — it may contain literal braces (STAPEL_BUS_ROUTES JSON)
+    # that str.format must never see.
+    rendered = template.format(**ctx)
+    return rendered.replace("{BROKER_ENV}", _broker_env(broker, task_broker))
+
+
+MONOLITH_COMPOSE_BASE = """\
+# Shared infrastructure — included by all environments.
+# Do not put service-specific overrides here.
+services:
+  db:
+    image: postgres:16
+    restart: unless-stopped
+    environment:
+      POSTGRES_USER: "${POSTGRES_USER:-stapel}"
+      POSTGRES_PASSWORD: "${POSTGRES_PASSWORD}"
+      POSTGRES_MULTIPLE_DATABASES: "stapel_main"
+    volumes:
+      - db-data:/var/lib/postgresql/data
+      - ./service-configs/postgres/ensure-databases.sh:/usr/local/bin/ensure-databases.sh:ro
+    command: >
+      bash -c "
+        docker-entrypoint.sh postgres &
+        until pg_isready -U $${POSTGRES_USER:-stapel}; do sleep 1; done
+        /usr/local/bin/ensure-databases.sh
+        wait
+      "
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U $${POSTGRES_USER:-stapel}"]
+      interval: 5s
+      timeout: 5s
+      retries: 10
+
+  redis:
+    image: redis:7-alpine
+    restart: unless-stopped
+    volumes:
+      - redis-data:/data
+
+{{BROKER_SERVICES}}  nginx:
+    image: nginx:alpine
+    restart: unless-stopped
+    ports:
+      - "${HTTP_PORT:-80}:80"
+    volumes:
+      - ./service-configs/nginx:/etc/nginx/conf.d:ro
+      - static-content:/staticfiles:ro
+      - media-content:/media:ro
+    depends_on: []
+
+volumes:
+  db-data:
+  redis-data:
+{{BROKER_VOLUMES}}  static-content:
+  media-content:
+"""
+
+MONOLITH_COMPOSE_LOCAL = """\
+include:
+  - docker-compose.base.yml
+
+services:
+  # Add services from their individual .yml files:
+  # svc-app:
+  #   extends:
+  #     file: svc-app.yml
+  #     service: svc-app
+  #   volumes:
+  #     - ./svc-app:/app
+  #     - ./stapel_core:/app/stapel_core:ro
+"""
+
+MONOLITH_COMPOSE_DEV = """\
+include:
+  - docker-compose.base.yml
+
+services:
+  # Add services from their individual .yml files:
+  # svc-app:
+  #   extends:
+  #     file: svc-app.yml
+  #     service: svc-app
+"""
+
+MONOLITH_ENV_TEMPLATE = """\
+# ─── Database ──────────────────────────────────────────────────────────────
+POSTGRES_USER=stapel
+POSTGRES_PASSWORD=change_me
+POSTGRES_HOST=db
+POSTGRES_PORT=5432
+
+# ─── Redis ─────────────────────────────────────────────────────────────────
+REDIS_URL=redis://redis:6379/0
+
+{{BROKER_ENV}}
+# ─── App ───────────────────────────────────────────────────────────────────
+SECRET_KEY=change_me_to_a_long_random_string
+JWT_SECRET_KEY=change_me_to_another_long_random_string
+ALLOWED_HOSTS={domain}
+SITE_URL={url}
+
+# ─── Email ─────────────────────────────────────────────────────────────────
+DEFAULT_FROM_EMAIL={company_name} <{company_email}>
+EMAIL_HOST=smtp.example.com
+EMAIL_PORT=587
+EMAIL_HOST_USER=
+EMAIL_HOST_PASSWORD=
+
+# ─── OAuth (optional) ───────────────────────────────────────────────────────
+GOOGLE_OAUTH2_KEY=
+GOOGLE_OAUTH2_SECRET=
+
+# ─── Run command ────────────────────────────────────────────────────────────
+RUN_CMD=gunicorn core.wsgi:application --bind 0.0.0.0:8000 --workers 2
+"""
+
+MONOLITH_GITIGNORE = """\
+.env
+*.pyc
+__pycache__/
+.venv/
+venv/
+*.egg-info/
+dist/
+build/
+htmlcov/
+.coverage
+*.sqlite3
+media/
+staticfiles/
+.DS_Store
+"""
+
+MICRO_COMPOSE_BASE = """\
+# Shared infrastructure for microservices stack.
+services:
+  db:
+    image: postgres:16
+    restart: unless-stopped
+    environment:
+      POSTGRES_USER: "${POSTGRES_USER:-stapel}"
+      POSTGRES_PASSWORD: "${POSTGRES_PASSWORD}"
+      POSTGRES_MULTIPLE_DATABASES: ""
+    volumes:
+      - db-data:/var/lib/postgresql/data
+      - ./service-configs/postgres/ensure-databases.sh:/usr/local/bin/ensure-databases.sh:ro
+    command: >
+      bash -c "
+        docker-entrypoint.sh postgres &
+        until pg_isready -U $${POSTGRES_USER:-stapel}; do sleep 1; done
+        /usr/local/bin/ensure-databases.sh
+        wait
+      "
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U $${POSTGRES_USER:-stapel}"]
+      interval: 5s
+      timeout: 5s
+      retries: 10
+
+  redis:
+    image: redis:7-alpine
+    restart: unless-stopped
+    volumes:
+      - redis-data:/data
+
+{{BROKER_SERVICES}}  nginx:
+    image: nginx:alpine
+    restart: unless-stopped
+    ports:
+      - "${HTTP_PORT:-80}:80"
+    volumes:
+      - ./service-configs/nginx:/etc/nginx/conf.d:ro
+      - static-content:/staticfiles:ro
+      - media-content:/media:ro
+    depends_on: []
+
+volumes:
+  db-data:
+  redis-data:
+{{BROKER_VOLUMES}}  static-content:
+  media-content:
+"""
+
+MICRO_COMPOSE_LOCAL = """\
+include:
+  - docker-compose.base.yml
+
+services:
+  # Add your services here.
+  # Run: stapel-new-service <name> --prefix svc-
+"""
+
+MICRO_ENV_TEMPLATE = """\
+# ─── Database ──────────────────────────────────────────────────────────────
+POSTGRES_USER=stapel
+POSTGRES_PASSWORD=change_me
+POSTGRES_HOST=db
+POSTGRES_PORT=5432
+
+# ─── Redis ─────────────────────────────────────────────────────────────────
+REDIS_URL=redis://redis:6379/0
+
+{{BROKER_ENV}}
+# ─── App ───────────────────────────────────────────────────────────────────
+SECRET_KEY=change_me_to_a_long_random_string
+JWT_SECRET_KEY=change_me_to_another_long_random_string
+ALLOWED_HOSTS={domain}
+SITE_URL={url}
+
+# ─── Email ─────────────────────────────────────────────────────────────────
+DEFAULT_FROM_EMAIL={company_name} <{company_email}>
+EMAIL_HOST=smtp.example.com
+EMAIL_PORT=587
+EMAIL_HOST_USER=
+EMAIL_HOST_PASSWORD=
+
+# ─── Run command ────────────────────────────────────────────────────────────
+RUN_CMD=gunicorn core.wsgi:application --bind 0.0.0.0:8000 --workers 2
+"""