@voltro/cli 0.1.0

package/templates/baselines/compose-mariadb/docker-compose.dev.yml

@@ -0,0 +1,117 @@
+# {{projectName}} full-stack DEV docker compose.
+#
+# Boots Postgres + apps with hot-reload. Each app container runs as
+# the HOST user (via `user: ${HOST_UID}:${HOST_GID}`) so files written
+# into the bind-mounted workspace land owned by you, not root. Without
+# this, switching between docker dev and native pnpm dev leaves
+# permission-denied errors on the cached vite deps.
+#
+# The pnpm-prebaked dev image (docker/dev.Dockerfile) is built once
+# on first `up`; subsequent `up` calls reuse the cached layer.
+#
+# Prereqs on the host BEFORE running this:
+#   1. pnpm install in the project root (deps need to exist on host
+#      because they're mounted in)
+#   2. .env in place — see .env.example
+#
+# Run:
+#   pnpm dev:docker        # wraps `HOST_UID=... HOST_GID=... docker compose up`
+#
+# Native-pnpm-dev alternative (faster HMR, no container overhead):
+#   pnpm dev:hybrid
+#
+# As you add apps to apps/, copy a service block and bump the port.
+
+x-node-defaults: &node-defaults
+  build:
+    context: ./
+    dockerfile: docker/dev.Dockerfile
+  image: {{projectName}}-dev:latest
+  user: "${HOST_UID:-1000}:${HOST_GID:-1000}"
+  volumes:
+    - ./:/workspace:cached
+  depends_on:
+    mariadb:
+      condition: service_healthy
+
+services:
+  mariadb:
+    image: mariadb:11
+    container_name: {{projectName}}-mariadb
+    restart: unless-stopped
+    environment:
+      MARIADB_ROOT_PASSWORD: root
+      MARIADB_DATABASE: {{projectNameSnake}}
+      MARIADB_USER: app
+      MARIADB_PASSWORD: app
+    ports:
+      - "3307:3306"
+    command:
+      - "--log-bin=mysql-bin"
+      - "--binlog-format=ROW"
+      - "--binlog-row-image=FULL"
+      - "--server-id=1"
+      - "--binlog-expire-logs-seconds=86400"
+    volumes:
+      - {{projectName}}-mariadbdata:/var/lib/mysql
+      - ./docker/mariadb-init.sql:/docker-entrypoint-initdb.d/10-replication.sql:ro
+    healthcheck:
+      test: ["CMD", "healthcheck.sh", "--connect", "--innodb_initialized"]
+      interval: 2s
+      timeout: 2s
+      retries: 15
+
+  minio:
+    image: minio/minio
+    container_name: {{projectName}}-minio
+    restart: unless-stopped
+    environment:
+      MINIO_ROOT_USER: minioadmin
+      MINIO_ROOT_PASSWORD: minioadmin
+    ports:
+      - "9000:9000"
+      - "9001:9001"
+    command: server /data --console-address ":9001"
+    volumes:
+      - {{projectName}}-miniodata:/data
+    healthcheck:
+      test: ["CMD", "mc", "ready", "local"]
+      interval: 3s
+      timeout: 2s
+      retries: 15
+
+  api:
+    <<: *node-defaults
+    container_name: {{projectName}}-api-dev
+    working_dir: /workspace/apps/{{projectName}}/api
+    command: pnpm voltro dev .
+    environment:
+      NODE_ENV: development
+      HOME: /tmp
+      DB_DIALECT: mariadb
+      DB_URL: mysql://app:app@mariadb:3306/{{projectNameSnake}}
+      CDC: "1"
+      STORAGE_PROVIDER: minio
+      S3_ENDPOINT: http://minio:9000
+      S3_BUCKET: {{projectNameSnake}}
+      S3_ACCESS_KEY_ID: minioadmin
+      S3_SECRET_ACCESS_KEY: minioadmin
+      S3_FORCE_PATH_STYLE: "1"
+      VOLTRO_SESSION_SECRET: ${VOLTRO_SESSION_SECRET:-dev-only-secret-please-rotate-in-prod}
+    ports:
+      - "4000:4000"
+
+  web:
+    <<: *node-defaults
+    container_name: {{projectName}}-web-dev
+    working_dir: /workspace/apps/{{projectName}}/web
+    command: pnpm voltro dev .
+    environment:
+      NODE_ENV: development
+      HOME: /tmp
+    ports:
+      - "5173:5173"
+
+volumes:
+  {{projectName}}-mariadbdata:
+  {{projectName}}-miniodata:

package/templates/baselines/compose-mariadb/docker-compose.prod.yml

@@ -0,0 +1,114 @@
+# {{projectName}} full-stack PROD docker compose.
+#
+# Builds locked images per app via docker/{api,web}.Dockerfile and
+# runs them behind Postgres. No source volumes — each app's code is
+# baked in at image-build time. Use this to smoke-test prod config
+# locally before deploying.
+#
+# This is NOT the production deploy target itself — that's helm or
+# your cloud provider's container runtime. This file gives parity
+# checking on localhost.
+#
+# Run:
+#   pnpm prod:build              # build all images (slow, ~5 min)
+#   pnpm prod:up                 # boot the stack
+#   pnpm prod:down               # tear down
+#
+# Different DB user from dev so accidental `pnpm db:reset` against
+# the dev compose doesn't wipe a prod-shape dataset you wanted to
+# poke at.
+
+services:
+  mariadb:
+    image: mariadb:11
+    container_name: {{projectName}}-mariadb-prod
+    restart: unless-stopped
+    environment:
+      MARIADB_ROOT_PASSWORD: ${MARIADB_ROOT_PASSWORD:-change-me-in-prod}
+      MARIADB_DATABASE: {{projectNameSnake}}
+      MARIADB_USER: app
+      MARIADB_PASSWORD: ${MARIADB_PASSWORD:-app}
+    ports:
+      - "3308:3306"
+    command:
+      - "--log-bin=mysql-bin"
+      - "--binlog-format=ROW"
+      - "--binlog-row-image=FULL"
+      - "--server-id=1"
+      - "--binlog-expire-logs-seconds=86400"
+    volumes:
+      - {{projectName}}-prod-mariadbdata:/var/lib/mysql
+      - ./docker/mariadb-init.sql:/docker-entrypoint-initdb.d/10-replication.sql:ro
+    healthcheck:
+      test: ["CMD", "healthcheck.sh", "--connect", "--innodb_initialized"]
+      interval: 5s
+      timeout: 3s
+      retries: 20
+
+  minio:
+    image: minio/minio
+    container_name: {{projectName}}-minio-prod
+    restart: unless-stopped
+    environment:
+      MINIO_ROOT_USER: ${S3_ACCESS_KEY_ID:-minioadmin}
+      MINIO_ROOT_PASSWORD: ${S3_SECRET_ACCESS_KEY:-minioadmin}
+    command: server /data --console-address ":9001"
+    volumes:
+      - {{projectName}}-prod-miniodata:/data
+    healthcheck:
+      test: ["CMD", "mc", "ready", "local"]
+      interval: 5s
+      timeout: 3s
+      retries: 20
+
+  api:
+    build:
+      context: ./
+      dockerfile: docker/api.Dockerfile
+      target: prod
+      args:
+        APP_PATH: apps/{{projectName}}/api
+    image: {{projectName}}-api:latest
+    container_name: {{projectName}}-api
+    restart: unless-stopped
+    environment:
+      NODE_ENV: production
+      DB_DIALECT: mariadb
+      DB_URL: mysql://app:${MARIADB_PASSWORD:-app}@mariadb:3306/{{projectNameSnake}}
+      CDC: "1"
+      STORAGE_PROVIDER: minio
+      S3_ENDPOINT: http://minio:9000
+      S3_BUCKET: {{projectNameSnake}}
+      S3_ACCESS_KEY_ID: ${S3_ACCESS_KEY_ID:-minioadmin}
+      S3_SECRET_ACCESS_KEY: ${S3_SECRET_ACCESS_KEY:-minioadmin}
+      S3_FORCE_PATH_STYLE: "1"
+      VOLTRO_SESSION_SECRET: ${VOLTRO_SESSION_SECRET:?must be set for prod compose}
+    ports:
+      - "4000:4000"
+    depends_on:
+      mariadb:
+        condition: service_healthy
+      minio:
+        condition: service_healthy
+
+  web:
+    build:
+      context: ./
+      dockerfile: docker/web.Dockerfile
+      target: prod
+      args:
+        APP_PATH: apps/{{projectName}}/web
+        APP_PORT: "5173"
+    image: {{projectName}}-web:latest
+    container_name: {{projectName}}-web
+    restart: unless-stopped
+    environment:
+      NODE_ENV: production
+    ports:
+      - "5173:5173"
+    depends_on:
+      - api
+
+volumes:
+  {{projectName}}-prod-mariadbdata:
+  {{projectName}}-prod-miniodata:

package/templates/baselines/compose-mariadb/docker-compose.yml

@@ -0,0 +1,79 @@
+# {{projectName}} infra docker compose — MariaDB (binlog CDC) + MinIO.
+#
+# Brought up by `pnpm db:up`. Apps run natively via `pnpm dev` against
+# this. For full-docker dev use `pnpm dev:docker`.
+#
+# MariaDB on 3307 (NOT default 3306) so it never clashes with a host
+# MySQL/MariaDB. The binlog flags are MANDATORY for Voltro's CDC reader:
+# real-time subscriptions fan out across replicas by tailing the binary
+# log (the binlog IS the message bus — no Redis/NATS).
+
+services:
+  mariadb:
+    image: mariadb:11
+    container_name: {{projectName}}-mariadb
+    restart: unless-stopped
+    environment:
+      MARIADB_ROOT_PASSWORD: root
+      MARIADB_DATABASE: {{projectNameSnake}}
+      MARIADB_USER: app
+      MARIADB_PASSWORD: app
+    ports:
+      - "3307:3306"
+    command:
+      # CDC requirements — ROW format + FULL row image so the reader sees
+      # complete before/after images; a server_id (unique per replica in
+      # prod — see the Helm baseline); generous binlog retention.
+      - "--log-bin=mysql-bin"
+      - "--binlog-format=ROW"
+      - "--binlog-row-image=FULL"
+      - "--server-id=1"
+      - "--binlog-expire-logs-seconds=86400"
+    volumes:
+      - {{projectName}}-mariadbdata:/var/lib/mysql
+      # Grants the app user REPLICATION SLAVE/CLIENT (the binlog reader needs it).
+      - ./docker/mariadb-init.sql:/docker-entrypoint-initdb.d/10-replication.sql:ro
+    healthcheck:
+      test: ["CMD", "healthcheck.sh", "--connect", "--innodb_initialized"]
+      interval: 2s
+      timeout: 2s
+      retries: 15
+
+  # Object storage for the file-storage primitive (@voltro/plugin-storage).
+  minio:
+    image: minio/minio
+    container_name: {{projectName}}-minio
+    restart: unless-stopped
+    environment:
+      MINIO_ROOT_USER: minioadmin
+      MINIO_ROOT_PASSWORD: minioadmin
+    ports:
+      - "9000:9000"   # S3 API
+      - "9001:9001"   # console
+    command: server /data --console-address ":9001"
+    volumes:
+      - {{projectName}}-miniodata:/data
+    healthcheck:
+      test: ["CMD", "mc", "ready", "local"]
+      interval: 3s
+      timeout: 2s
+      retries: 15
+
+  # One-shot: create the app bucket + make it publicly readable (avatars
+  # are served via the public /_voltro/storage/:id route).
+  createbuckets:
+    image: minio/mc
+    depends_on:
+      minio:
+        condition: service_healthy
+    entrypoint: >
+      /bin/sh -c "
+      mc alias set local http://minio:9000 minioadmin minioadmin &&
+      mc mb -p local/{{projectNameSnake}} &&
+      mc anonymous set download local/{{projectNameSnake}};
+      exit 0;
+      "
+
+volumes:
+  {{projectName}}-mariadbdata:
+  {{projectName}}-miniodata:

package/templates/baselines/helm/.env.example

@@ -0,0 +1,39 @@
+# Voltro local env — helm baseline.
+#
+# Helm is your DEPLOY target, not your dev loop. This .env governs
+# local dev (run via `pnpm dev` against a local Postgres).
+#
+# In-cluster env values come from the Helm chart's ConfigMap +
+# Secret, NOT from this file. See charts/voltro-app/templates/.
+
+# Local Postgres (your install — or a docker run sidecar — or any
+# managed instance you can reach from your laptop).
+DB_URL=postgres://app:app@localhost:5432/{{projectName}}
+
+# Local session signing secret. The chart's Secret is the source of
+# truth in the cluster.
+VOLTRO_SESSION_SECRET=dev-only-secret-please-rotate-in-prod
+
+# ─── Optional backends — ALL OFF by default; uncomment to activate ───────────
+# The cache and the durable KV each run on a zero-infra default (in-process
+# memory / your SQL store). Point either at a RESP server (Redis / Valkey /
+# KeyDB / Dragonfly / Upstash) ONLY when you want cross-instance sharing.
+# In-cluster these come from the chart's ConfigMap/Secret; this file governs
+# local dev. Enablement is per concern — a bare REDIS_URL is NOT a master
+# switch; each reads its own <NAME>_REDIS_URL first, then a shared REDIS_URL.
+
+# @voltro/cache → Redis: a distributed query/result cache. `voltro add redis`
+# wires this for you (flips app.config `cache: 'redis'` + adds the infra).
+# CACHE_BACKEND=redis
+# CACHE_REDIS_URL=redis://localhost:6379
+
+# @voltro/kv → Redis: durable `ctx.kv`. Default backend is `database`
+# (durable, shared across replicas, survives restarts) — leave it unless you
+# specifically want KV on Redis. If you do, use a PERSISTENT redis (AOF/RDB),
+# NOT an ephemeral cache-only one: an eviction/restart is data loss for
+# durable KV. See docs → Caching → Key-value backends.
+# KV_BACKEND=redis
+# KV_REDIS_URL=redis://localhost:6379
+
+# One server for everything, instead of the per-concern URLs above:
+# REDIS_URL=redis://localhost:6379

package/templates/baselines/helm/README.md

@@ -0,0 +1,98 @@
+# Helm baseline
+
+Kubernetes-first deploy via a Helm chart at `charts/voltro-app/`.
+Per-env overlay values for dev / staging / prod. Local dev still uses
+native pnpm or docker-compose — Helm is for deploy, not the dev loop.
+
+## Layout
+
+```
+.
+├── charts/
+│   └── voltro-app/
+│       ├── Chart.yaml
+│       ├── values.yaml              # defaults
+│       ├── values-dev.yaml          # dev cluster overrides
+│       ├── values-staging.yaml      # staging overrides
+│       ├── values-prod.yaml         # prod overrides
+│       ├── .helmignore
+│       └── templates/
+│           ├── _helpers.tpl
+│           ├── deployment-api.yaml
+│           ├── deployment-web.yaml
+│           ├── service-api.yaml
+│           ├── service-web.yaml
+│           ├── ingress.yaml
+│           ├── configmap.yaml
+│           ├── secret.yaml
+│           ├── postgres-statefulset.yaml
+│           └── postgres-service.yaml
+└── deploy/README.md
+```
+
+## Common flows
+
+### Local dev
+
+You don't run Helm for local dev. Either:
+- `pnpm dev` (native, fastest) + your own local Postgres, OR
+- Add the **compose** baseline back temporarily for full-docker dev:
+  `voltro baseline set compose` (you can then add helm back; baselines
+  aren't mutually exclusive at the file level, only one is "active"
+  for tracking purposes).
+
+### Cluster dev (kind / minikube / k3d)
+
+```sh
+kind create cluster --name {{projectName}}-dev
+pnpm helm:lint
+pnpm helm:install:dev
+kubectl -n {{projectName}}-dev get pods
+kubectl -n {{projectName}}-dev port-forward svc/{{projectName}}-web 5173:5173
+```
+
+### Staging / prod deploy
+
+```sh
+# Set kubeconfig to your prod cluster first
+pnpm helm:install:prod
+```
+
+GitOps-style (recommended): commit the chart + values, let ArgoCD or
+Flux watch the repo and sync changes. The `pnpm helm:install:*` scripts
+are CLI escape hatches, not the primary deploy path.
+
+## Secrets
+
+`templates/secret.yaml` ships an EXAMPLE secret with `change-me`
+placeholders. **Never commit real secrets**. Production options:
+
+- **Sealed Secrets** (Bitnami) — encrypted-in-git
+- **External Secrets Operator** — pulls from AWS Secrets Manager / Vault
+- **SOPS** + helm-secrets plugin — encrypted YAML
+
+Pick one for your cluster + replace the placeholder secret accordingly.
+
+## Postgres in the chart vs external
+
+`values.yaml` defaults to `postgres.embedded: true` which provisions a
+single-replica StatefulSet inside the cluster. Fine for dev, **not fine
+for prod** — you want a managed Postgres (RDS / Cloud SQL / Crunchy
+Operator). Switch by setting:
+
+```yaml
+# values-prod.yaml
+postgres:
+  embedded: false
+  externalUrl: postgres://...   # from a Secret, not literal
+```
+
+## Switching baselines
+
+`voltro baseline set compose` → restores docker-compose, keeps the
+Helm chart on disk (you may want both: compose for local, helm for
+deploy). `voltro baseline set bare` → strips everything containerized.
+
+The "active" baseline is tracked in `.voltro/baseline.json` — it
+controls what `voltro baseline status` reports and what `voltro
+baseline sync` (future) regenerates.

package/templates/baselines/helm/baseline.json

@@ -0,0 +1,53 @@
+{
+  "id": "helm",
+  "displayName": "Helm Chart",
+  "summary": "Kubernetes-first deploy via Helm chart. Per-env overlays (dev/staging/prod). Postgres (embedded StatefulSet) OR MariaDB (external, binlog CDC) via a db.dialect switch. Per-pod POD_NAME/POD_IP downward-API for CDC server_id + workflow-runner host; 4-replica prod; S3/MinIO storage.",
+  "tags": ["kubernetes", "helm", "k8s", "prod", "mariadb", "cdc", "storage"],
+  "recommendedFor": "k8s shops; GitOps setups (ArgoCD / Flux); multi-cluster prod deploys.",
+  "tradeoffs": {
+    "pros": [
+      "Standard k8s manifests — fits any CNCF cluster",
+      "Per-env overlays via values-{dev,staging,prod}.yaml",
+      "GitOps-friendly: tools like ArgoCD watch the chart and sync",
+      "Horizontal autoscaling, rolling updates, health probes built in"
+    ],
+    "cons": [
+      "Requires a running k8s cluster to test (kind/minikube/k3d for local)",
+      "Helm + k8s YAML is more verbose than docker-compose",
+      "Local dev STILL uses native pnpm / docker-compose — Helm is a deploy target, not a dev loop",
+      "Operator must know k8s (ingress, cert-manager, secrets management)"
+    ]
+  },
+  "files": [
+    ".env.example",
+    "charts/voltro-app/Chart.yaml",
+    "charts/voltro-app/values.yaml",
+    "charts/voltro-app/values-dev.yaml",
+    "charts/voltro-app/values-staging.yaml",
+    "charts/voltro-app/values-prod.yaml",
+    "charts/voltro-app/.helmignore",
+    "charts/voltro-app/templates/_helpers.tpl",
+    "charts/voltro-app/templates/deployment-api.yaml",
+    "charts/voltro-app/templates/deployment-web.yaml",
+    "charts/voltro-app/templates/service-api.yaml",
+    "charts/voltro-app/templates/service-web.yaml",
+    "charts/voltro-app/templates/ingress.yaml",
+    "charts/voltro-app/templates/configmap.yaml",
+    "charts/voltro-app/templates/secret.yaml",
+    "charts/voltro-app/templates/postgres-statefulset.yaml",
+    "charts/voltro-app/templates/postgres-service.yaml",
+    "deploy/README.md"
+  ],
+  "packageJsonScripts": {
+    "dev":              "turbo run dev",
+    "build":            "turbo run build",
+    "test":             "turbo run test",
+    "typecheck":        "turbo run typecheck",
+    "helm:lint":        "helm lint charts/voltro-app",
+    "helm:template:dev":   "helm template {{projectName}}-dev charts/voltro-app -f charts/voltro-app/values-dev.yaml",
+    "helm:install:dev":    "helm upgrade --install {{projectName}}-dev charts/voltro-app -f charts/voltro-app/values-dev.yaml --namespace {{projectName}}-dev --create-namespace",
+    "helm:install:staging":"helm upgrade --install {{projectName}}-staging charts/voltro-app -f charts/voltro-app/values-staging.yaml --namespace {{projectName}}-staging --create-namespace",
+    "helm:install:prod":   "helm upgrade --install {{projectName}}-prod charts/voltro-app -f charts/voltro-app/values-prod.yaml --namespace {{projectName}}-prod --create-namespace",
+    "helm:uninstall:dev":  "helm uninstall {{projectName}}-dev --namespace {{projectName}}-dev"
+  }
+}

package/templates/baselines/helm/charts/voltro-app/.helmignore

@@ -0,0 +1,10 @@
+# Helm ignore — files not packaged into the chart tarball.
+.DS_Store
+.git/
+.gitignore
+.idea/
+.vscode/
+*.swp
+*.swo
+*.tmpl.local
+node_modules/

package/templates/baselines/helm/charts/voltro-app/Chart.yaml

@@ -0,0 +1,10 @@
+apiVersion: v2
+name: {{projectName}}
+description: Helm chart for {{projectName}} — a Voltro framework project.
+type: application
+version: 0.1.0
+appVersion: "0.0.0"
+
+# Maintainers — replace with your team contact.
+maintainers:
+  - name: {{projectName}} team

package/templates/baselines/helm/charts/voltro-app/templates/_helpers.tpl

@@ -0,0 +1,36 @@
+{{/*
+Helm chart helpers for the {{projectName}} chart.
+
+Helm uses {{ ... }} syntax; the Voltro scaffolder only substitutes a
+whitelisted set of tokens ({{projectName}} etc.) so other {{ ... }}
+fragments pass through untouched into the installed chart.
+*/}}
+
+{{- define "voltro-app.name" -}}
+{{- default .Chart.Name .Values.nameOverride | trunc 63 | trimSuffix "-" -}}
+{{- end -}}
+
+{{- define "voltro-app.fullname" -}}
+{{- if .Values.fullnameOverride -}}
+{{- .Values.fullnameOverride | trunc 63 | trimSuffix "-" -}}
+{{- else -}}
+{{- $name := default .Chart.Name .Values.nameOverride -}}
+{{- printf "%s-%s" .Release.Name $name | trunc 63 | trimSuffix "-" -}}
+{{- end -}}
+{{- end -}}
+
+{{- define "voltro-app.labels" -}}
+app.kubernetes.io/name: {{ include "voltro-app.name" . }}
+app.kubernetes.io/instance: {{ .Release.Name }}
+app.kubernetes.io/version: {{ .Chart.AppVersion | quote }}
+app.kubernetes.io/managed-by: {{ .Release.Service }}
+helm.sh/chart: {{ printf "%s-%s" .Chart.Name .Chart.Version }}
+{{- end -}}
+
+{{- define "voltro-app.serviceAccountName" -}}
+{{- if .Values.serviceAccount.create -}}
+{{- default (include "voltro-app.fullname" .) .Values.serviceAccount.name -}}
+{{- else -}}
+{{- default "default" .Values.serviceAccount.name -}}
+{{- end -}}
+{{- end -}}

package/templates/baselines/helm/charts/voltro-app/templates/configmap.yaml

@@ -0,0 +1,13 @@
+{{- if .Values.api.enabled -}}
+apiVersion: v1
+kind: ConfigMap
+metadata:
+  name: {{ include "voltro-app.fullname" . }}-config
+  labels:
+    {{- include "voltro-app.labels" . | nindent 4 }}
+data:
+  NODE_ENV: production
+  {{- range $key, $value := .Values.api.env }}
+  {{ $key }}: {{ $value | quote }}
+  {{- end }}
+{{- end }}