@massu/core 1.3.0 → 1.4.0

package/commands/massu-deploy.python-systemd.md

@@ -0,0 +1,163 @@
+---
+name: massu-deploy
+description: "Deploy a Python service supervised by systemd (Linux) — restart the user unit, poll health, tail journalctl, diff before/after, rollback if unhealthy"
+allowed-tools: Bash(*), Read(*), Grep(*), Glob(*)
+---
+
+# Massu Deploy: Python Service — systemd (Linux)
+
+Restarts a Python service running under a `systemd --user` unit on Linux. Use this variant when your `massu.config.yaml` declares `config.python.service_label` and your host is Linux.
+
+## Workflow Position
+
+```
+/massu-push -> /massu-deploy (systemd variant)
+```
+
+This command restarts a production service. **If the service handles financial, transactional, or otherwise consequential state, real data is at risk** — pre-flight checks are mandatory.
+
+---
+
+## NON-NEGOTIABLE RULES
+
+- **Never deploy with uncommitted changes** — push first via `/massu-push`
+- **Never deploy with failing tests** — test suite must be green before this runs
+- **Always restart-and-probe** — file-saved ≠ process-running-the-fix
+- **Never kill processes without identifying them first** — confirm the unit name before sending any signal
+
+---
+
+## Pre-flight
+
+```bash
+# 1. Branch + working tree clean
+test -z "$(git status --porcelain)" || { echo "DIRTY — commit/stash first"; exit 1; }
+
+# 2. Tests green
+pytest -x 2>&1 | tail -10
+
+# 3. Confirm the unit is active
+systemctl --user status {{config.python.service_label | default("<service-label>")}} --no-pager | head -20
+
+# 4. Capture current health for diff
+curl -sS http://localhost:8000/health | python3 -m json.tool \
+  > /tmp/{{config.python.service_label | default("service")}}-health-before.json
+```
+
+---
+
+## Approval Gate
+
+```
+===============================================================================
+APPROVAL REQUIRED — SYSTEMD RESTART
+===============================================================================
+
+Service unit  : {{config.python.service_label | default("<service-label>")}}
+Supervisor    : systemd --user (Linux)
+Pre-flight    : PASS
+
+This will:
+  1. systemctl --user restart {{config.python.service_label | default("<service-label>")}}
+  2. Poll /health every 2s (max 60s) until 200
+  3. Smoke /health + any critical endpoint
+  4. Diff before/after health JSON
+  5. On failure: print rollback command
+
+Reply "approve" or "abort".
+===============================================================================
+```
+
+---
+
+## Restart
+
+```bash
+systemctl --user restart {{config.python.service_label | default("<service-label>")}}
+```
+
+If the unit is system-level (not user-level), drop `--user` and run with `sudo`.
+
+---
+
+## Poll Health
+
+```bash
+for i in $(seq 1 30); do
+  sleep 2
+  status=$(curl -sS -o /dev/null -w "%{http_code}" http://localhost:8000/health || echo "000")
+  [ "$status" = "200" ] && { echo "READY after ${i} polls"; break; }
+  echo "poll ${i}: ${status}"
+done
+```
+
+---
+
+## Smoke + Diff
+
+```bash
+curl -sS http://localhost:8000/health | python3 -m json.tool \
+  > /tmp/{{config.python.service_label | default("service")}}-health-after.json
+
+diff \
+  /tmp/{{config.python.service_label | default("service")}}-health-before.json \
+  /tmp/{{config.python.service_label | default("service")}}-health-after.json \
+  | head -50
+```
+
+---
+
+## Tail Startup Logs
+
+```bash
+# Recent errors from the unit (2-minute window)
+journalctl --user -u {{config.python.service_label | default("<service-label>")}} \
+  --since "2 minutes ago" --no-pager | grep -iE "error|warn" | head -20
+
+# Follow live (Ctrl-C to stop)
+journalctl --user -u {{config.python.service_label | default("<service-label>")}} -f --no-pager
+
+# Full boot for this unit
+journalctl --user -u {{config.python.service_label | default("<service-label>")}} \
+  -b --no-pager | tail -100
+```
+
+---
+
+## Rollback
+
+If `/health` does not return 200 within 60s, or any smoke check fails:
+
+```bash
+git revert HEAD --no-edit
+systemctl --user restart {{config.python.service_label | default("<service-label>")}}
+```
+
+Then page yourself or your on-call — an unhealthy production service is an incident.
+
+---
+
+## Useful systemd Diagnostics
+
+```bash
+# Check if the unit file needs a daemon-reload after editing the .service file
+systemctl --user daemon-reload
+
+# Show the resolved unit definition (useful to verify ExecStart path)
+systemctl --user cat {{config.python.service_label | default("<service-label>")}}
+
+# List recent restarts / crash history
+systemctl --user show {{config.python.service_label | default("<service-label>")}} \
+  --property=NRestarts,ActiveState,SubState
+```
+
+---
+
+## Audit Log
+
+```bash
+echo "$(date -u +%FT%TZ) deploy surface=systemd sha=$(git rev-parse HEAD) unit={{config.python.service_label | default("<service-label>")}} actor=$(whoami)" \
+  >> data/audit/deploys.log
+```
+
+Done. Report: unit name, sha, restart time, health status, any warnings.

package/commands/massu-scaffold-page.swift.md

@@ -12,11 +12,11 @@ Creates a SwiftUI View + `@MainActor` ViewModel + Decodable response model. Suit
 
 | File | Purpose |
 |------|---------|
-| `${paths.swift_source}/Features/<feature>/Views/<Name>View.swift` | SwiftUI view |
-| `${paths.swift_source}/Features/<feature>/ViewModels/<Name>ViewModel.swift` | `@MainActor` ObservableObject |
-| `${paths.swift_source}/Features/<feature>/Models/<Name>Response.swift` | Decodable matching API contract |
+| `{{paths.swift_source | default("ios/Sources")}}/Features/<feature>/Views/<Name>View.swift` | SwiftUI view |
+| `{{paths.swift_source | default("ios/Sources")}}/Features/<feature>/ViewModels/<Name>ViewModel.swift` | `@MainActor` ObservableObject |
+| `{{paths.swift_source | default("ios/Sources")}}/Features/<feature>/Models/<Name>Response.swift` | Decodable matching API contract |
 
-> **Path resolution**: substitute `${paths.swift_source}` against your project's `massu.config.yaml` (`paths.swift_source`). If unset, fall back to whatever the project already uses (`Sources/`, `apps/ios/<App>/<App>/`, etc.).
+> **Path resolution**: substitute `{{paths.swift_source | default("ios/Sources")}}` against your project's `massu.config.yaml` (`paths.swift_source`). If unset, fall back to whatever the project already uses (`Sources/`, `apps/ios/<App>/<App>/`, etc.).
 
 ## Template — `<Name>View.swift`
 
@@ -58,10 +58,10 @@ final class <Name>ViewModel: ObservableObject {
     @Published var isLoading = false
     @Published var error: String?
 
-    // Substitute APIClient with the project's actual API wrapper.
-    private let api: APIClient
+    // Substitute {{detected.swift.api_client_class | default("APIClient")}} with the project's actual API wrapper.
+    private let api: {{detected.swift.api_client_class | default("APIClient")}}
 
-    init(api: APIClient = .shared) {
+    init(api: {{detected.swift.api_client_class | default("APIClient")}} = .shared) {
         self.api = api
     }
 
@@ -97,7 +97,7 @@ struct <Name>Response: Decodable {
 
 - **Decodable silent nil**: with `JSONDecoder.keyDecodingStrategy = .convertFromSnakeCase`, a typo'd property decodes to nil with NO error. Hand-verify every property against a real API response — entire screens have shipped showing dead data because of this.
 - **`.system(size:weight:design:)` argument order**: weight before design. Reversed args silently fall back to default font.
-- **Biometric authentication**: for sensitive actions, use `LAPolicy.deviceOwnerAuthenticationWithBiometrics` — NOT `deviceOwnerAuthentication` (which falls back to a passcode and defeats the gate).
+- **Biometric authentication**: for sensitive actions, use `LAPolicy.{{detected.swift.biometric_policy | default("deviceOwnerAuthenticationWithBiometrics")}}` — NOT `deviceOwnerAuthentication` (which falls back to a passcode and defeats the gate).
 - **Sheet state**: never clear `@State` sheet-bound vars in async callbacks; use `.onDismiss` instead.
 - **XcodeGen target naming**: cross-platform projects often split iOS / visionOS into separate targets (e.g., `<App>_iOS` / `<App>_visionOS`). Build the platform-specific scheme, NOT the umbrella name.
 - **`@MainActor` on view models**: any `@Published` field that drives UI must be set on the main actor. Async work updates state via `await MainActor.run { ... }` if the function isn't already main-actor-isolated.
@@ -107,10 +107,10 @@ struct <Name>Response: Decodable {
 1. Ask: which feature folder? Which target (iOS / visionOS / both)?
 2. Read the API endpoint's actual JSON response (e.g., `curl -sS http://<service>/api/<endpoint> | python3 -m json.tool`) — copy the EXACT key names so the Decodable can't drift.
 3. Write the three files.
-4. Add the new files to your project's manifest (`project.yml` for XcodeGen, or directly in Xcode for hand-managed projects); regen if needed: `cd ${paths.swift_source}/.. && xcodegen`.
+4. Add the new files to your project's manifest (`project.yml` for XcodeGen, or directly in Xcode for hand-managed projects); regen if needed: `cd {{paths.swift_source | default("ios/Sources")}}/.. && xcodegen`.
 5. Build the right scheme:
    ```bash
-   cd ${paths.swift_source}/.. && xcodebuild -scheme <Target>_iOS -destination 'generic/platform=iOS Simulator' build | tail -20
+   cd {{paths.swift_source | default("ios/Sources")}}/.. && xcodebuild -scheme <Target>_iOS -destination 'generic/platform=iOS Simulator' build | tail -20
    ```
 
 ## START NOW

package/commands/massu-scaffold-router.python-django.md

@@ -0,0 +1,153 @@
+---
+name: massu-scaffold-router
+description: "Django-specific scaffold for {{paths.python_source | default("django_app")}}/views.py — creates function-based and class-based views with login_required, plus urls.py registration"
+allowed-tools: Bash(*), Read(*), Write(*), Edit(*), Grep(*), Glob(*)
+---
+
+# Scaffold New Django View
+
+Creates Django views in `{{paths.python_source | default("django_app")}}` following the project's conventions. Covers function-based views (FBV), class-based views (CBV), and the corresponding `urls.py` registration. Auth guard uses `{{detected.python.auth_dep | default("login_required")}}`.
+
+## What Gets Created
+
+| File | Purpose |
+|------|---------|
+| `{{paths.python_source | default("django_app")}}/views.py` | FBV + CBV examples |
+| `{{paths.python_source | default("django_app")}}/urls.py` | URL routing registration |
+| `{{paths.python_test | default("tests")}}/test_<name>_views.py` | View tests (auth + happy path) |
+
+> **Auth decorator**: this template uses `{{detected.python.auth_dep | default("login_required")}}` — sourced from the massu introspector. If your project uses a custom decorator or `@permission_required`, swap it in.
+
+## Template — Function-Based View
+
+```python
+"""<Name> views — describe purpose in one line."""
+
+import logging
+
+from django.contrib.auth.decorators import login_required
+from django.http import HttpRequest, JsonResponse
+from django.views.decorators.http import require_http_methods
+
+# Use the detected auth decorator if your project wraps the Django built-in.
+# from .auth import {{detected.python.auth_dep | default("login_required")}}
+
+logger = logging.getLogger(__name__)
+
+
+@{{detected.python.auth_dep | default("login_required")}}
+@require_http_methods(["GET"])
+def list_items(request: HttpRequest) -> JsonResponse:
+    """List items. Read-only — login guard is sufficient."""
+    return JsonResponse({"ok": True, "items": []})
+
+
+@{{detected.python.auth_dep | default("login_required")}}
+@require_http_methods(["POST"])
+def create_item(request: HttpRequest) -> JsonResponse:
+    """Create an item. Mutating — ensure the auth decorator enforces the right role."""
+    # Validate POST body here — never trust raw request.POST for numeric / typed fields.
+    logger.info("item created by user=%s", request.user.pk)
+    return JsonResponse({"ok": True})
+```
+
+## Template — Class-Based View
+
+```python
+from django.contrib.auth.mixins import LoginRequiredMixin
+from django.views import View
+from django.http import HttpRequest, JsonResponse
+
+
+class ItemListView(LoginRequiredMixin, View):
+    """Class-based list view. LoginRequiredMixin redirects unauthenticated users."""
+
+    def get(self, request: HttpRequest) -> JsonResponse:
+        return JsonResponse({"ok": True, "items": []})
+
+
+class ItemDetailView(LoginRequiredMixin, View):
+    def get(self, request: HttpRequest, pk: int) -> JsonResponse:
+        # Fetch from DB; raise Http404 if not found.
+        return JsonResponse({"ok": True, "id": pk})
+```
+
+## Template — `urls.py` Registration
+
+```python
+from django.urls import path
+from . import views
+
+app_name = "<name>"
+
+urlpatterns = [
+    path("items/", views.list_items, name="list"),
+    path("items/create/", views.create_item, name="create"),
+    # CBV registration:
+    path("items/<int:pk>/", views.ItemDetailView.as_view(), name="detail"),
+]
+```
+
+Then include in the project's root `urls.py`:
+
+```python
+from django.urls import path, include
+
+urlpatterns = [
+    # ...
+    path("api/<name>/", include("<app_label>.urls")),
+]
+```
+
+## Test scaffold (`{{paths.python_test | default("tests")}}/test_<name>_views.py`)
+
+```python
+import pytest
+from django.test import Client
+from django.contrib.auth import get_user_model
+
+User = get_user_model()
+
+
+@pytest.mark.django_db
+def test_list_items_requires_auth(client: Client):
+    response = client.get("/api/<name>/items/")
+    # login_required redirects; DRF returns 403 — accept either.
+    assert response.status_code in (302, 401, 403)
+
+
+@pytest.mark.django_db
+def test_list_items_authenticated(client: Client, django_user_model):
+    user = django_user_model.objects.create_user(username="tester", password="pass")
+    client.force_login(user)
+    response = client.get("/api/<name>/items/")
+    assert response.status_code == 200
+    data = response.json()
+    assert data["ok"] is True
+```
+
+## Django Conventions
+
+- **Always guard mutating views** with `{{detected.python.auth_dep | default("login_required")}}` (or a role/permission mixin for sensitive operations).
+- **Use `LoginRequiredMixin` for CBVs** — decorator-only auth on CBVs can be bypassed via HTTP method routing.
+- **Never trust `request.POST` for typed fields** — validate with a Django Form or DRF serializer.
+- **Atomic DB writes** — wrap multi-step mutations in `django.db.transaction.atomic`.
+- **CSRF** — `@require_http_methods` does NOT exempt CSRF. For JSON APIs, either use DRF's `CSRFExemptSessionAuthentication` or enforce the CSRF token client-side.
+- **Avoid N+1** — use `select_related` / `prefetch_related` in list views.
+
+## Process
+
+1. Ask user: which Django app (`app_label`)? What URL prefix? What views are needed?
+2. Confirm path: `{{paths.python_source | default("django_app")}}/views.py`.
+3. Write or append to `views.py`; write the `urls.py` snippet.
+4. Include the URL conf in the project root `urls.py`.
+5. Run migrations if the new views touch new models: `python manage.py makemigrations && python manage.py migrate`.
+6. Smoke: `python manage.py runserver` and curl or use the test client.
+
+## START NOW
+
+Ask the user:
+1. Which Django app (label) owns these views?
+2. What URL prefix? (e.g. `api/<name>/`)
+3. Function-based or class-based views (or both)?
+4. Does any view touch sensitive state? — that decides the auth decorator vs mixin.

package/commands/massu-scaffold-router.python-fastapi.md

@@ -0,0 +1,145 @@
+---
+name: massu-scaffold-router
+description: "FastAPI-specific scaffold for {{paths.python_source | default("app")}}/routers/ — creates the router file, registers it in main.py, adds Pydantic schemas, and applies the project's detected auth dependency"
+allowed-tools: Bash(*), Read(*), Write(*), Edit(*), Grep(*), Glob(*)
+---
+
+# Scaffold New FastAPI Router
+
+Creates a complete FastAPI router following the project's existing conventions in `{{paths.python_source | default("app")}}/routers/`. Auth dependency sourced from the massu introspector's `detected.python.auth_dep` (falls back to `get_current_user` if not detected).
+
+## What Gets Created
+
+| File | Purpose |
+|------|---------|
+| `{{paths.python_source | default("app")}}/routers/<name>.py` | Router with endpoints |
+| Registration in `{{paths.python_source | default("app")}}/main.py` | `app.include_router(...)` |
+| `{{paths.python_test | default("tests")}}/test_<name>_router.py` | Router test (auth + happy path + error path) |
+
+> **Auth dependency**: this template uses `{{detected.python.auth_dep | default("get_current_user")}}` — the value introspected from your codebase by massu. If your project uses a different dependency, adjust the import and `Depends(...)` call.
+
+> **Path resolution**: `paths.python_source` and `paths.python_test` come from `massu.config.yaml`. If those keys are not declared, the fallbacks `app/` and `tests/` are used.
+
+## Template
+
+```python
+"""<Name> API — describe purpose in one line.
+
+Plan: <plan-id> if applicable. Owner: <subsystem>.
+"""
+
+import logging
+
+from fastapi import APIRouter, Depends, HTTPException, Request
+from pydantic import BaseModel, Field
+
+# Auth dependency detected from your codebase.
+from ._shared import {{detected.python.auth_dep | default("get_current_user")}}
+# from ..auth import require_role  # for endpoints that mutate sensitive state
+
+logger = logging.getLogger(__name__)
+
+router = APIRouter(prefix="{{detected.python.api_prefix_base | default("/api")}}/<name>", tags=["<name>"])
+
+
+class FooRequest(BaseModel):
+    symbol: str = Field(min_length=1, max_length=16)
+    # ALWAYS bound numeric inputs — open-ended floats are how unit-mismatch and
+    # APY-style overflow bugs sneak through.
+    quantity: float = Field(gt=0, le=1_000_000)
+
+
+class FooResponse(BaseModel):
+    ok: bool
+    payload: dict
+
+
+@router.get("/items")
+async def list_items(
+    request: Request,
+    user: dict = Depends({{detected.python.auth_dep | default("get_current_user")}}),
+) -> FooResponse:
+    """List items. Read-only — base auth dependency is sufficient."""
+    # Async-only I/O. Wrap external calls with `async with asyncio.timeout(N)`;
+    # client-library timeouts (httpx, aiohttp) alone do not cover DNS/TLS hangs.
+    return FooResponse(ok=True, payload={"items": []})
+
+
+@router.post("/orders")
+async def create_order(
+    body: FooRequest,
+    request: Request,
+    user: dict = Depends({{detected.python.auth_dep | default("get_current_user")}}),  # SWAP for require_role(...) for any state-mutating action
+) -> FooResponse:
+    """Mutating endpoint — enforce role-based auth (or service-token) here."""
+    logger.info("order created symbol=%s qty=%s user=%s", body.symbol, body.quantity, user.get("user_id"))
+    return FooResponse(ok=True, payload={"symbol": body.symbol, "qty": body.quantity})
+```
+
+## Registration in `main.py`
+
+```python
+# at top of file with other router imports
+from .routers.<name> import router as <name>_router
+
+# in the section where other routers are included
+app.include_router(<name>_router)
+```
+
+## Test scaffold (`{{paths.python_test | default("tests")}}/test_<name>_router.py`)
+
+```python
+import pytest
+from httpx import AsyncClient, ASGITransport
+
+from <project_package>.main import app  # substitute your top-level package
+
+
+@pytest.mark.asyncio
+async def test_list_items_requires_auth():
+    async with AsyncClient(transport=ASGITransport(app=app), base_url="http://test") as ac:
+        r = await ac.get("{{detected.python.api_prefix_base | default("/api")}}/<name>/items")
+    assert r.status_code in (401, 403)
+
+
+@pytest.mark.asyncio
+async def test_create_order_input_validation(auth_headers):
+    async with AsyncClient(transport=ASGITransport(app=app), base_url="http://test") as ac:
+        r = await ac.post("{{detected.python.api_prefix_base | default("/api")}}/<name>/orders", json={"symbol": "", "quantity": 0}, headers=auth_headers)
+    assert r.status_code == 422
+```
+
+## FastAPI Conventions (apply in any project)
+
+- **Auth choice**:
+  - `Depends({{detected.python.auth_dep | default("get_current_user")}})` for read-only endpoints
+  - A role-gated dependency (e.g. `require_role("admin")`) for ANY state-mutating endpoint — non-negotiable for safety-critical surfaces
+  - Service-token / machine-auth checks happen BEFORE any "auth disabled" dev bypass
+- **Async only**: every I/O call uses `async def` + `await`. Wrap external calls in `async with asyncio.timeout(N)` — internal client-library timeouts are not enough for DNS/TLS hangs.
+- **Bound numeric inputs**: `Field(gt=..., le=...)` on every numeric. Open-ended ranges produce overflow bugs in financial / metric / quantity contexts.
+- **Validate input strings**: symbols, IDs, slugs — use a project-local validator, never trust raw `str` for downstream lookups.
+- **No hardcoded sentinel values**: `0`, `0.00`, `""`, `None` are usually indistinguishable from real values. Be deliberate.
+- **Module-level state**: locks must be lazy (`asyncio.Lock()` at module top binds to the wrong loop). Background `create_task()` returns must be stored in a module-level set with `add_done_callback` to prevent GC.
+- **Silent drops log WARNING** — never DEBUG. Anything dropped at scale must be visible in production logs.
+- **Dependency injection**: any class that touches sensitive state (trades, memory, billing) should accept its dependencies via constructor or `set_*` — never assume singleton is pre-wired.
+
+## Process
+
+1. Ask user: what subsystem owns this router? What endpoints does it need? Which are read-only vs mutating?
+2. Confirm path: `{{paths.python_source | default("app")}}/routers/<name>.py`. If the name collides with an existing router, stop and ask.
+3. Write the router file using the template above; pick the right auth dependency per endpoint.
+4. Write the test scaffold and confirm it imports cleanly: `pytest {{paths.python_test | default("tests")}}/test_<name>_router.py -x --collect-only`.
+5. Add the `app.include_router(<name>_router)` line to `main.py` AFTER the file exists (split-commit safety).
+6. Verify route registration:
+   ```bash
+   python -c "from <project_package>.main import app; print([r.path for r in app.routes if '/api/<name>' in str(r.path)])"
+   ```
+7. Restart the service and curl-smoke the new endpoint (tests passing ≠ running process has the change).
+
+## START NOW
+
+Ask the user:
+1. What subsystem/feature owns this router?
+2. What's the URL prefix? (default: `{{detected.python.api_prefix_base | default("/api")}}/<name>`)
+3. What endpoints, and which are mutating vs read-only?
+4. Does any endpoint touch sensitive state (trades, billing, user permissions)? That decides whether to use a role-gated dependency vs the base auth dependency.