@massu/core 1.2.1 → 1.4.0-soak.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-deploy.python.md

@@ -0,0 +1,200 @@
+---
+name: massu-deploy
+description: "Deploy a Python service (FastAPI / asgi) to production. Default target is a long-running process supervised by launchd, systemd, pm2, or docker — NOT Vercel. Asks which surface before acting."
+allowed-tools: Bash(*), Read(*), Grep(*), Glob(*)
+---
+
+> **Shared rules apply.** Read `${paths.commands}/_shared-preamble.md` before proceeding.
+
+# Massu Deploy: Python Service Production Deploy
+
+## Workflow Position
+
+```
+/massu-create-plan -> /massu-plan -> /massu-loop -> /massu-commit -> /massu-push -> /massu-deploy
+(CREATE)           (AUDIT)        (IMPLEMENT)   (COMMIT)        (PUSH)         (DEPLOY)
+```
+
+This command deploys to production. **If the service is doing anything financial, transactional, or otherwise consequential, real money / data integrity is at risk** — pre-flight checks are mandatory.
+
+---
+
+## CRITICAL — Deployment Surfaces
+
+A non-Vercel Python project usually has multiple deploy surfaces. Ask the user which one(s) before proceeding:
+
+| Surface | What "deploy" means | Authority |
+|---------|---------------------|-----------|
+| **Service** (default) | Restart the supervised process — `launchctl kickstart`, `systemctl restart`, `pm2 restart`, or `docker compose up -d` | The actual production brain |
+| **Static / docs** | rsync / S3 sync (if applicable) | Static site only |
+| **Worker(s)** | Restart any background workers (celery, rq, custom asyncio task runners) | Background processing |
+
+**There is NO assumption of Vercel.** Do NOT run `vercel --prod` from this template. If the user wants a Vercel deploy of a separate sub-project, route them to a different surface or scaffold a dedicated script.
+
+---
+
+## NON-NEGOTIABLE RULES
+
+- **Never deploy with uncommitted changes** — push first via `/massu-push`
+- **Never deploy with failing tests** — `pytest` (or your project's test runner) must be green
+- **Always restart-and-probe** — file-saved ≠ process-running-the-fix. After restart, hit a health endpoint and diff before/after
+- **Never kill processes without identifying them first** — get the PID, log line, or supervisor label before sending any signal
+- **Live-trading or live-billing flag flips are a separate concern** — this command does not flip `auto_*_mode`, `*_live`, `production_*` flags. Use the dedicated approval flow
+
+---
+
+## START NOW
+
+### Step 0: Ask the user
+
+```
+===============================================================================
+PYTHON DEPLOY — Which surface?
+===============================================================================
+
+  service   Restart the supervised Python service (default)
+  workers   Restart background workers (celery / rq / custom)
+  all       service + workers
+  static    rsync / S3 sync (only if applicable)
+
+Which? [service / workers / all / static]
+===============================================================================
+```
+
+---
+
+## Path A: Service (default)
+
+Substitute `${supervisor}` with whatever your project actually uses (`launchd`, `systemd`, `pm2`, `docker`). Substitute `${service_label}` with the actual label / unit name from `massu.config.yaml` (`deploy.python.service_label`) or from your project's process manager.
+
+### Pre-flight
+
+```bash
+# 1. Branch + working tree clean
+test -z "$(git status --porcelain)" || { echo "DIRTY — commit/stash first"; exit 1; }
+
+# 2. Tests green (impacted area only — full suite is for /massu-push)
+${paths.python_test_command:-pytest} -x 2>&1 | tail -10
+
+# 3. Identify the running process (NEVER blind-kill)
+# launchd: launchctl list | grep ${service_label}
+# systemd: systemctl status ${service_label}
+# pm2:     pm2 jlist | jq '.[] | select(.name=="${service_label}")'
+# docker:  docker compose ps ${service_label}
+
+# 4. Capture current health for diff
+curl -sS ${health_url:-http://localhost:8000/health} | python3 -m json.tool > /tmp/${service_label}-health-before.json
+```
+
+### Approval gate
+
+```
+===============================================================================
+APPROVAL REQUIRED — RESTART ${service_label}
+===============================================================================
+
+Pre-flight: PASS
+Branch: <current>
+HEAD: <sha>
+Last service uptime: <etime>
+
+This will:
+  1. Restart ${service_label} via ${supervisor}
+  2. Wait 5s, poll /health until 200 (max 60s)
+  3. Smoke: /health, /api/feature-flags (if applicable), one critical endpoint
+  4. Diff before/after health responses
+  5. If any check fails: print rollback (`git revert HEAD` + restart)
+
+Reply "approve" or "abort".
+===============================================================================
+```
+
+### Restart + verify
+
+Pick the line that matches your supervisor:
+
+```bash
+# launchd
+launchctl kickstart -k gui/$(id -u)/${service_label}
+
+# systemd (user)
+systemctl --user restart ${service_label}
+
+# pm2
+pm2 restart ${service_label}
+
+# docker compose
+docker compose up -d --force-recreate ${service_label}
+```
+
+Then probe:
+
+```bash
+# Poll until ready (60s budget)
+for i in $(seq 1 30); do
+  sleep 2
+  status=$(curl -sS -o /dev/null -w "%{http_code}" ${health_url:-http://localhost:8000/health} || echo "000")
+  [ "$status" = "200" ] && { echo "READY after ${i} polls"; break; }
+done
+
+# Smoke + diff
+curl -sS ${health_url:-http://localhost:8000/health} | python3 -m json.tool > /tmp/${service_label}-health-after.json
+diff /tmp/${service_label}-health-before.json /tmp/${service_label}-health-after.json | head -50
+
+# Tail the supervisor log for startup errors
+# launchd:
+log show --predicate 'subsystem == "${service_label}"' --last 2m --info 2>/dev/null | grep -iE "error|warn" | head -20
+# systemd:
+# journalctl --user -u ${service_label} --since "2 minutes ago" | grep -iE "error|warn" | head -20
+# pm2:
+# pm2 logs ${service_label} --lines 100 --nostream | grep -iE "error|warn" | head -20
+```
+
+### Rollback
+
+If `/health` does not return 200 within 60s, or smoke fails:
+
+```bash
+git revert HEAD --no-edit && <restart-command-from-above>
+```
+
+Then page yourself or your on-call: an unhealthy production service is an incident.
+
+---
+
+## Path B: Workers
+
+```bash
+# Restart background workers (celery / rq / custom asyncio runners)
+# Substitute the supervisor label list for your project's worker names.
+for label in ${worker_labels}; do
+  echo "restarting $label..."
+  # launchd: launchctl kickstart -k gui/$(id -u)/$label
+  # systemd: systemctl --user restart $label
+  # pm2:     pm2 restart $label
+done
+
+# Verify each worker is processing again — push a no-op job if you have one,
+# or read the queue depth before/after.
+```
+
+---
+
+## Path C: Static (only if applicable)
+
+```bash
+# Build static site, rsync, or aws s3 sync — fill in your project's pipeline.
+# This is intentionally NOT a default; only run if your project has a static deploy target.
+```
+
+---
+
+## After ANY surface deploys
+
+Save the deployment sha and timestamp to your project's audit log so the boundary is visible:
+
+```bash
+echo "$(date -u +%FT%TZ) deploy surface=<surface> sha=$(git rev-parse HEAD) actor=$(whoami)" >> ${paths.audit_log:-data/audit/deploys.log}
+```
+
+Done. Report: surface, sha, time, smoke results, any warnings.

package/commands/massu-scaffold-page.md

@@ -1,24 +1,40 @@
 ---
 name: massu-scaffold-page
-description: "When user wants to create a new page, route, or section in the app — scaffolds the page component, layout, loading/error states, and tRPC integration"
+description: "When user wants to create a new page, screen, or view — asks which framework target (Next.js, SwiftUI, FastAPI templates, Rust web), then scaffolds component / view / handler with project conventions"
 allowed-tools: Bash(*), Read(*), Write(*), Edit(*), Grep(*), Glob(*)
 ---
 
-# Scaffold New Page
+# Scaffold New Page / View
 
-Creates a complete Next.js App Router page following all project patterns.
+This default template is **framework-agnostic**. It asks the user (or, when invoked by an agent, infers from `massu.config.yaml`) which target to scaffold, then dispatches to one of the embedded patterns below.
 
-## What Gets Created
+> **If your project ships a stack-specific variant** of this template (e.g., `massu-scaffold-page.swift.md`), the variant is preferred and this default is not installed. See `${paths.commands}/README.md` for the variant-resolution rules.
 
-| File | Purpose |
-|------|---------|
-| `page.tsx` | Main page component with Suspense boundary |
-| `loading.tsx` | Skeleton loading state |
-| `error.tsx` | Error boundary with retry |
+## Step 1 — Pick a target
 
-## Template
+Ask the user (or read `framework.primary` / `framework.languages` from the consumer's `massu.config.yaml`):
+
+| Stack | Path A: web | Path B: native / mobile | Path C: backend rendered |
+|-------|-------------|-------------------------|--------------------------|
+| TypeScript / Next.js | `app/<route>/page.tsx` + loading + error | — | — |
+| Swift / SwiftUI | — | `Features/<feature>/Views/<Name>View.swift` (+ ViewModel + Response) | — |
+| Python / FastAPI | — | — | Jinja template + handler in `routers/<name>.py` |
+| Rust / Axum | — | — | `src/handlers/<name>.rs` returning `Html` or JSON |
+
+If the user is unsure, default to whatever `framework.primary` points at.
+
+---
+
+## Pattern 1 — Next.js App Router page
+
+### What gets created
+
+- `${paths.web_source}/app/<route>/page.tsx`
+- `${paths.web_source}/app/<route>/loading.tsx`
+- `${paths.web_source}/app/<route>/error.tsx`
+
+### `page.tsx`
 
-### page.tsx
 ```tsx
 import { Suspense } from 'react';
 import { PageContent } from './page-content';
@@ -26,82 +42,179 @@ import Loading from './loading';
 
 export default function Page() {
   return (
-    <div className="page-container">
-      <Suspense fallback={<Loading />}>
-        <PageContent />
-      </Suspense>
-    </div>
+    <Suspense fallback={<Loading />}>
+      <PageContent />
+    </Suspense>
   );
 }
 ```
 
-### page-content.tsx (with params)
+### `page-content.tsx`
+
 ```tsx
 'use client';
 
-import { use } from 'react';
-import { api } from '@/trpc/react';
-
-export function PageContent({ params }: { params: Promise<{ id: string }> }) {
-  const { id } = use(params);
-  const { data, isLoading } = api.routerName.getById.useQuery({ id });
-
-  if (isLoading) return <Loading />;
-
-  return (
-    <>
-      <PageHeader title="Page Title" />
-      {/* Page content */}
-    </>
-  );
+import { useEffect, useState } from 'react';
+
+export function PageContent() {
+  const [data, setData] = useState<unknown>(null);
+  const [error, setError] = useState<string | null>(null);
+
+  useEffect(() => {
+    // Substitute the URL with your project's API base — tRPC client, REST URL, etc.
+    fetch(`${process.env.NEXT_PUBLIC_API_BASE ?? '/api'}/<endpoint>`, {
+      credentials: 'include',
+    })
+      .then(async (r) => {
+        if (!r.ok) throw new Error(`HTTP ${r.status}`);
+        setData(await r.json());
+      })
+      .catch((e: Error) => setError(e.message));
+  }, []);
+
+  if (error) throw new Error(error);
+  if (!data) return null;
+  return <pre>{JSON.stringify(data, null, 2)}</pre>;
 }
 ```
 
-### loading.tsx
-```tsx
-import { Skeleton } from '@/components/ui/skeleton';
+### `loading.tsx` / `error.tsx`
 
+```tsx
+// loading.tsx — show a skeleton, NOT a flash of empty state.
 export default function Loading() {
-  return (
-    <div className="page-container">
-      <Skeleton className="h-8 w-48 mb-6" />
-      <Skeleton className="h-64 w-full" />
-    </div>
-  );
+  return <div className="page-skeleton" />;
 }
 ```
 
-### error.tsx
 ```tsx
+// error.tsx — must be a client component. Provides a retry handle to the user.
 'use client';
-
 export default function Error({ error, reset }: { error: Error; reset: () => void }) {
   return (
-    <div className="page-container">
-      <h2>Something went wrong</h2>
-      <p className="text-muted-foreground">{error.message}</p>
+    <div role="alert">
+      <p>Something went wrong: {error.message}</p>
       <button onClick={reset}>Try again</button>
     </div>
   );
 }
 ```
 
-## Gotchas
+### Verification
+
+```bash
+npm run build 2>&1 | tail -20   # or pnpm/yarn equivalent
+```
+
+---
+
+## Pattern 2 — SwiftUI iOS / visionOS view
+
+(Full version available as the `.swift.md` variant of this template.)
+
+### What gets created
+
+- `${paths.swift_source}/Features/<feature>/Views/<Name>View.swift`
+- `${paths.swift_source}/Features/<feature>/ViewModels/<Name>ViewModel.swift`
+- `${paths.swift_source}/Features/<feature>/Models/<Name>Response.swift`
+
+### Sketch
+
+```swift
+struct <Name>View: View {
+    @StateObject private var viewModel = <Name>ViewModel()
+    var body: some View {
+        Group {
+            if viewModel.isLoading { ProgressView() }
+            else if let err = viewModel.error { ErrorState(message: err) { Task { await viewModel.load() } } }
+            else { content }
+        }
+        .task { await viewModel.load() }
+    }
+    private var content: some View { /* real content */ EmptyView() }
+}
+
+@MainActor
+final class <Name>ViewModel: ObservableObject {
+    @Published var data: <Name>Response?
+    @Published var isLoading = false
+    @Published var error: String?
+    func load() async { /* fetch and decode */ }
+}
+```
+
+**Critical**: With `JSONDecoder.keyDecodingStrategy = .convertFromSnakeCase`, mismatched property names decode to nil silently. Hand-verify every Decodable property against a real API response.
+
+### Verification
+
+```bash
+xcodebuild -scheme <Target>_iOS -destination 'generic/platform=iOS Simulator' build | tail -20
+```
+
+---
+
+## Pattern 3 — FastAPI Jinja-rendered page
 
-- **ALWAYS use `page-container`** class on root div — never `container mx-auto`
-- **Suspense boundaries** are REQUIRED for pages using `use(params)` or `useSearchParams()`
-- **protectedProcedure** for ALL tRPC queries that need auth
-- **No `sm:page-container`** — only exception is mobile chat layouts
-- **Breadcrumbs**: Add to PageHeader if page is nested (e.g., `/crm/contacts/[id]`)
+### What gets created
 
-## Process
+- `${paths.python_source}/routers/<name>.py` (Jinja-rendering handler)
+- `${paths.python_templates}/<name>.html`
 
-1. Ask user: What URL path? What data does it fetch?
-2. Determine route segment: `src/app/(app)/[section]/[subsection]/`
-3. Create all 3 files (page.tsx, loading.tsx, error.tsx)
-4. If data-fetching: verify tRPC router exists, add query
-5. Run `npx tsc --noEmit` to verify types
+### Sketch
+
+```python
+from fastapi import APIRouter, Depends, Request
+from fastapi.responses import HTMLResponse
+from fastapi.templating import Jinja2Templates
+
+from ._shared import get_current_user
+
+router = APIRouter()
+templates = Jinja2Templates(directory="${paths.python_templates}")
+
+@router.get("/<route>", response_class=HTMLResponse)
+async def render(request: Request, user: dict = Depends(get_current_user)):
+    return templates.TemplateResponse("<name>.html", {"request": request, "user": user})
+```
+
+**Critical**: this pattern serves HTML from FastAPI directly; for pure-API endpoints, use `/massu-scaffold-router` instead.
+
+---
+
+## Pattern 4 — Axum (Rust) HTML handler
+
+### What gets created
+
+- `${paths.rust_source}/handlers/<name>.rs`
+- Wire-up in `src/main.rs` or `src/router.rs` via `.route("/<path>", get(<name>::handler))`.
+
+### Sketch
+
+```rust
+use axum::{response::Html, routing::get, Router};
+
+pub fn router() -> Router {
+    Router::new().route("/<path>", get(handler))
+}
+
+async fn handler() -> Html<&'static str> {
+    Html("<!doctype html><meta charset='utf-8'><title>Page</title><h1>Hello</h1>")
+}
+```
+
+### Verification
+
+```bash
+cargo build 2>&1 | tail -10 && cargo test --quiet
+```
+
+---
 
 ## START NOW
 
-Ask the user what page to create and where it should live in the route hierarchy.
+Ask the user (in this order):
+
+1. **Which target?** TS / Next.js · Swift / SwiftUI · Python / FastAPI · Rust / Axum. Default to `framework.primary` from `massu.config.yaml` if the user is unsure.
+2. What's the URL path / feature name?
+3. What does the page render, and which API endpoint feeds it?
+4. Any auth requirements? (logged-in only · role-gated · biometric-gated for sensitive actions)