@massu/core 1.3.0 → 1.4.0

package/commands/README.md

@@ -14,13 +14,17 @@ This README covers:
 ## 1. Variant filename convention
 
 ```
-<base>.md                # default — used when no variant matches
-<base>.python.md         # FastAPI / Django / generic Python
-<base>.swift.md          # SwiftUI / iOS / visionOS
-<base>.rust.md           # axum / actix / generic Rust
-<base>.typescript.md     # reserved for future use; currently no variants ship
+<base>.md                        # default — used when no variant matches
+<base>.python.md                 # FastAPI / Django / generic Python (one-axis)
+<base>.python-fastapi.md         # Python + FastAPI (two-axis: lang + sub-framework)
+<base>.python-django.md          # Python + Django (two-axis: lang + sub-framework)
+<base>.swift.md                  # SwiftUI / iOS / visionOS
+<base>.rust.md                   # axum / actix / generic Rust
+<base>.typescript.md             # reserved for future use; currently no variants ship
 ```
 
+The two-axis form (`<base>.<lang>-<framework>.md`) is tried BEFORE the one-axis (`<base>.<lang>.md`) form. It is selected when the consumer's config declares `framework.languages.<lang>.framework = "<sub-framework>"` (e.g. `fastapi` or `django`).
+
 The variant convention applies **only at the top level** of `packages/core/commands/`. Files inside subdirectories (e.g., `_shared-references/`, `massu-loop/references/`) are copied recursively as-is — no variant resolution, no dot-skip filtering. Future authors can use dotted filenames in nested dirs without losing them to the variant filter.
 
 The variant convention is **opt-in**: a template that does NOT ship any `<base>.<variant>.md` siblings is variant-agnostic and the unsuffixed `<base>.md` is used everywhere.
@@ -100,11 +104,22 @@ Prints the resolved template content (post-variant-resolution) to stdout. Used i
 
 | Base | Variants |
 |------|----------|
-| `massu-scaffold-router` | `.python.md` (FastAPI) |
+| `massu-scaffold-router` | `.python-fastapi.md` (FastAPI — two-axis), `.python-django.md` (Django — two-axis) |
 | `massu-scaffold-page` | `.swift.md` (SwiftUI), regenerated default with embedded Next.js / FastAPI / SwiftUI / Rust examples |
-| `massu-deploy` | `.python.md` (launchd / systemd / pm2 / docker) |
+| `massu-deploy` | `.python-launchd.md`, `.python-systemd.md`, `.python-docker.md`, `.python-fly.md` (all two-axis) |
+
+All other top-level templates ship as variant-agnostic defaults (one `<base>.md`).
+
+### Template variable substitution
+
+As of `@massu/core@1.3.0`, template files may contain `{{variable.path}}` and `{{variable.path | default("fallback")}}` placeholders. These are rendered against the consumer's `massu.config.yaml` (all `framework.*`, `paths.*`, and `config.*` fields) plus the `detected.*` block written by the codebase introspector (e.g. `detected.python.auth_dep`, `detected.swift.api_client_class`).
+
+Rules:
+- Every `{{detected.*}}` reference MUST include a `| default("...")` fallback — introspection may return nothing.
+- Use `\{{` to emit a literal `{{` in the rendered output (e.g. Go/Docker format strings).
+- A render error on a single file causes that file to be skipped (stderr message only); the rest of the install continues.
 
-All other 57 top-level templates ship as variant-agnostic defaults (one `<base>.md`).
+Pass `--skip-commands` to `massu init` or `massu refresh` to suppress command installation entirely.
 
 ## 6. Adding a new variant
 
@@ -112,11 +127,8 @@ All other 57 top-level templates ship as variant-agnostic defaults (one `<base>.
 2. The default `<base>.md` should remain generic (or be regenerated if it was previously stack-specific — see `massu-scaffold-page.md` for the pattern of an embedded multi-stack default).
 3. Add a row to the table in section 5.
 4. Add a test case to `packages/core/src/__tests__/install-commands.test.ts` that exercises the new variant against a fixture config.
-5. Update `docs/internal/2026-04-26-template-variant-audit.md` (the audit doc) with the new label.
 
 ## 7. Reference
 
-- Plan: `/Users/ekoultra/hedge/docs/plans/2026-04-26-massu-stack-aware-command-templates.md`
-- Audit: `docs/internal/2026-04-26-template-variant-audit.md`
 - Implementation: `packages/core/src/commands/install-commands.ts`
 - Tests: `packages/core/src/__tests__/install-commands.test.ts` and `show-template.test.ts`

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

@@ -0,0 +1,170 @@
+---
+name: massu-deploy
+description: "Deploy a containerized Python service via docker compose — force-recreate the service container, health-check poll, diff before/after, rollback if unhealthy"
+allowed-tools: Bash(*), Read(*), Grep(*), Glob(*)
+---
+
+# Massu Deploy: Python Service — Docker Compose
+
+Force-recreates the Docker container for a Python service using `docker compose`. Use this variant when your service is containerized and `massu.config.yaml` declares `config.python.service_label` matching the compose service name.
+
+## Workflow Position
+
+```
+/massu-push -> /massu-deploy (docker variant)
+```
+
+This command redeploys a running container. **If the service handles financial, transactional, or 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** — `docker compose up` ≠ the new image is healthy
+- **Never stop containers without identifying them first** — confirm the compose service name before running any destructive command
+
+---
+
+## 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 service is running
+docker compose ps {{config.python.service_label | default("<service-label>")}}
+
+# 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
+```
+
+---
+
+## Build (if image needs rebuilding)
+
+```bash
+# Rebuild the image for this service only (skip if using a pre-built registry image)
+docker compose build {{config.python.service_label | default("<service-label>")}}
+```
+
+---
+
+## Approval Gate
+
+```
+===============================================================================
+APPROVAL REQUIRED — DOCKER COMPOSE REDEPLOY
+===============================================================================
+
+Compose service : {{config.python.service_label | default("<service-label>")}}
+Supervisor      : docker compose
+Pre-flight      : PASS
+
+This will:
+  1. docker compose up -d --force-recreate {{config.python.service_label | default("<service-label>")}}
+  2. Poll /health every 2s against the container (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".
+===============================================================================
+```
+
+---
+
+## Redeploy
+
+```bash
+docker compose up -d --force-recreate {{config.python.service_label | default("<service-label>")}}
+```
+
+`--force-recreate` ensures the container is replaced even if the image tag didn't change. Omit if you only want `up` to no-op on unchanged images.
+
+---
+
+## Poll Container 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
+```
+
+If the compose file declares a `HEALTHCHECK` directive, you can also poll the Docker health state:
+
+```bash
+for i in $(seq 1 30); do
+  sleep 2
+  state=$(docker inspect --format='\{{.State.Health.Status}}' \
+    "$(docker compose ps -q {{config.python.service_label | default("<service-label>")}})") 2>/dev/null || state="unknown"
+  [ "$state" = "healthy" ] && { echo "Container healthy after ${i} polls"; break; }
+  echo "poll ${i}: $state"
+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 Container Logs
+
+```bash
+# Last 100 lines, filtered for errors
+docker compose logs {{config.python.service_label | default("<service-label>")}} \
+  --tail=100 --no-log-prefix | grep -iE "error|warn" | head -20
+
+# Follow live (Ctrl-C to stop)
+docker compose logs -f {{config.python.service_label | default("<service-label>")}} --no-log-prefix
+```
+
+---
+
+## Rollback
+
+If `/health` does not return 200 within 60s, or any smoke check fails:
+
+```bash
+# Option A: revert code + redeploy
+git revert HEAD --no-edit
+docker compose build {{config.python.service_label | default("<service-label>")}}
+docker compose up -d --force-recreate {{config.python.service_label | default("<service-label>")}}
+
+# Option B: roll back to the previous image tag (if using a registry)
+# docker compose pull {{config.python.service_label | default("<service-label>")}}:<prev-tag>
+# docker compose up -d --force-recreate {{config.python.service_label | default("<service-label>")}}
+```
+
+Then page yourself or your on-call — an unhealthy production container is an incident.
+
+---
+
+## Audit Log
+
+```bash
+echo "$(date -u +%FT%TZ) deploy surface=docker sha=$(git rev-parse HEAD) service={{config.python.service_label | default("<service-label>")}} actor=$(whoami)" \
+  >> data/audit/deploys.log
+```
+
+Done. Report: compose service name, image digest or sha, restart time, health status, any warnings.

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

@@ -0,0 +1,189 @@
+---
+name: massu-deploy
+description: "Deploy a Python service to Fly.io — flyctl deploy, status check, log tail, rollback if unhealthy"
+allowed-tools: Bash(*), Read(*), Grep(*), Glob(*)
+---
+
+# Massu Deploy: Python Service — Fly.io
+
+Deploys a Python service to Fly.io using `flyctl deploy`. Use this variant when your project targets Fly.io and has a `fly.toml` in the repository root. The app name comes from `fly.toml` (or `config.python.service_label` as a fallback).
+
+## Workflow Position
+
+```
+/massu-push -> /massu-deploy (fly variant)
+```
+
+This command deploys to a live Fly.io app. **If the app 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 check status after deploy** — `flyctl deploy` success ≠ the new release is healthy
+- **Never force a deploy to fix a broken deploy** — diagnose first, then decide
+
+---
+
+## 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 flyctl is authenticated and the app exists
+flyctl status --app {{config.python.service_label | default("<app-name>")}} 2>&1 | head -20
+
+# 4. Note the current release number for rollback reference
+flyctl releases --app {{config.python.service_label | default("<app-name>")}} --limit 3
+```
+
+---
+
+## `fly.toml` — Key Fields to Verify
+
+Before deploying, confirm these sections exist in `fly.toml`:
+
+```toml
+app = "{{config.python.service_label | default("<app-name>")}}"
+primary_region = "<region>"  # e.g. "ord", "lax", "iad"
+
+[build]
+  # Dockerfile or builder block
+
+[http_service]
+  internal_port = 8000
+  force_https = true
+  auto_stop_machines = true
+  auto_start_machines = true
+
+[[vm]]
+  memory = "512mb"
+  cpu_kind = "shared"
+  cpus = 1
+
+[checks]
+  [checks.health]
+    grace_period = "10s"
+    interval = "30s"
+    method = "GET"
+    path = "/health"
+    protocol = "https"
+    timeout = "10s"
+```
+
+Missing a `[checks.health]` block means Fly.io won't automatically detect an unhealthy release.
+
+---
+
+## Approval Gate
+
+```
+===============================================================================
+APPROVAL REQUIRED — FLY.IO DEPLOY
+===============================================================================
+
+App name   : {{config.python.service_label | default("<app-name>")}}
+Platform   : Fly.io
+Pre-flight : PASS
+
+This will:
+  1. flyctl deploy --app {{config.python.service_label | default("<app-name>")}}
+  2. Wait for Fly.io health checks to pass (built-in to flyctl)
+  3. flyctl status to confirm all instances are running
+  4. Smoke /health endpoint
+  5. On failure: print rollback command
+
+Reply "approve" or "abort".
+===============================================================================
+```
+
+---
+
+## Deploy
+
+```bash
+flyctl deploy --app {{config.python.service_label | default("<app-name>")}}
+```
+
+`flyctl deploy` builds the image (or reuses a cached layer), pushes to the Fly.io registry, creates a new release, and waits for health checks. Pass `--strategy rolling` or `--strategy bluegreen` if your app supports it.
+
+---
+
+## Post-Deploy Status
+
+```bash
+# Confirm all machines are healthy
+flyctl status --app {{config.python.service_label | default("<app-name>")}}
+
+# Show the new release
+flyctl releases --app {{config.python.service_label | default("<app-name>")}} --limit 1
+```
+
+---
+
+## Smoke
+
+```bash
+# Hit the public health endpoint (replace with your actual hostname)
+APP_HOST=$(flyctl info --app {{config.python.service_label | default("<app-name>")}} --hostname 2>/dev/null | head -1 || echo "{{config.python.service_label | default("<app-name>")}}.fly.dev")
+curl -sS "https://${APP_HOST}/health" | python3 -m json.tool
+```
+
+---
+
+## Tail Logs
+
+```bash
+# Live log stream (Ctrl-C to stop)
+flyctl logs --app {{config.python.service_label | default("<app-name>")}}
+
+# Filter for errors in recent output
+flyctl logs --app {{config.python.service_label | default("<app-name>")}} 2>&1 | grep -iE "error|warn|exception" | head -30
+```
+
+---
+
+## Rollback
+
+If health checks fail or the smoke check returns non-200:
+
+```bash
+# Roll back to the previous release
+flyctl releases --app {{config.python.service_label | default("<app-name>")}} --limit 5
+flyctl deploy --image <previous-image-ref> --app {{config.python.service_label | default("<app-name>")}}
+```
+
+Or use the Fly dashboard's "Rollback" button if the release number is known.
+
+Then page yourself or your on-call — an unhealthy Fly.io release is an incident.
+
+---
+
+## Secrets Management
+
+Do NOT hard-code secrets in `fly.toml`. Use Fly secrets:
+
+```bash
+# Set a secret (prompts for value if omitted)
+flyctl secrets set MY_SECRET_KEY=<value> --app {{config.python.service_label | default("<app-name>")}}
+
+# List current secret names (values are redacted)
+flyctl secrets list --app {{config.python.service_label | default("<app-name>")}}
+```
+
+---
+
+## Audit Log
+
+```bash
+echo "$(date -u +%FT%TZ) deploy surface=fly sha=$(git rev-parse HEAD) app={{config.python.service_label | default("<app-name>")}} actor=$(whoami)" \
+  >> data/audit/deploys.log
+```
+
+Done. Report: app name, release number, deploy time, health status, any warnings.

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

@@ -0,0 +1,144 @@
+---
+name: massu-deploy
+description: "Deploy a Python service supervised by launchd (macOS) — restart the launchd agent, poll health, diff before/after, rollback if unhealthy"
+allowed-tools: Bash(*), Read(*), Grep(*), Glob(*)
+---
+
+# Massu Deploy: Python Service — launchd (macOS)
+
+Restarts a Python service running under `launchd` on macOS. Use this variant when your `massu.config.yaml` declares `config.python.service_label` and your host is macOS.
+
+## Workflow Position
+
+```
+/massu-push -> /massu-deploy (launchd 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 label 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 launchd agent is registered
+launchctl list | grep {{config.python.service_label | default("<service-label>")}}
+
+# 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 — LAUNCHD RESTART
+===============================================================================
+
+Service label : {{config.python.service_label | default("<service-label>")}}
+Supervisor    : launchd (macOS)
+Pre-flight    : PASS
+
+This will:
+  1. launchctl kickstart -k gui/$(id -u)/{{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
+launchctl kickstart -k gui/$(id -u)/{{config.python.service_label | default("<service-label>")}}
+```
+
+The `-k` flag kills the existing process before relaunching — equivalent to a clean restart. If you need to stop without restart, use `launchctl kill SIGTERM gui/$(id -u)/{{config.python.service_label | default("<service-label>")}}` instead.
+
+---
+
+## 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
+# Unified log (most reliable for launchd-managed services)
+log show \
+  --predicate 'subsystem == "{{config.python.service_label | default("<service-label>")}}"' \
+  --last 2m --info 2>/dev/null | grep -iE "error|warn" | head -20
+
+# Alternative: stderr from the plist's StandardErrorPath
+# cat ~/Library/Logs/{{config.python.service_label | default("<service-label>")}}/stderr.log | tail -40
+```
+
+---
+
+## Rollback
+
+If `/health` does not return 200 within 60s, or any smoke check fails:
+
+```bash
+git revert HEAD --no-edit
+launchctl kickstart -k gui/$(id -u)/{{config.python.service_label | default("<service-label>")}}
+```
+
+Then page yourself or your on-call — an unhealthy production service is an incident.
+
+---
+
+## Audit Log
+
+```bash
+echo "$(date -u +%FT%TZ) deploy surface=launchd sha=$(git rev-parse HEAD) label={{config.python.service_label | default("<service-label>")}} actor=$(whoami)" \
+  >> data/audit/deploys.log
+```
+
+Done. Report: label, sha, restart time, health status, any warnings.