@voltro/cli 0.1.0

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

@@ -0,0 +1,89 @@
+# {{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:
+    postgres:
+      condition: service_healthy
+
+services:
+  postgres:
+    image: postgres:17-alpine
+    container_name: {{projectName}}-postgres
+    restart: unless-stopped
+    environment:
+      POSTGRES_USER: app
+      POSTGRES_PASSWORD: app
+      POSTGRES_DB: {{projectNameSnake}}
+    ports:
+      - "5433:5432"
+    command:
+      - "postgres"
+      - "-c"
+      - "wal_level=logical"
+      - "-c"
+      - "max_wal_senders=4"
+      - "-c"
+      - "max_replication_slots=4"
+    volumes:
+      - {{projectName}}-pgdata:/var/lib/postgresql/data
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U app -d {{projectNameSnake}}"]
+      interval: 2s
+      timeout: 2s
+      retries: 10
+
+  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_URL: postgres://app:app@postgres:5432/{{projectNameSnake}}
+      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}}-pgdata:

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

@@ -0,0 +1,87 @@
+# {{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:
+  postgres:
+    image: postgres:17-alpine
+    container_name: {{projectName}}-postgres-prod
+    restart: unless-stopped
+    environment:
+      POSTGRES_USER: {{projectNameSnake}}
+      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:-change-me-in-prod}
+      POSTGRES_DB: {{projectNameSnake}}
+    ports:
+      - "5434:5432"
+    command:
+      - "postgres"
+      - "-c"
+      - "wal_level=logical"
+      - "-c"
+      - "max_wal_senders=4"
+      - "-c"
+      - "max_replication_slots=4"
+    volumes:
+      - {{projectName}}-prod-pgdata:/var/lib/postgresql/data
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U {{projectNameSnake}} -d {{projectNameSnake}}"]
+      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_URL: postgres://{{projectNameSnake}}:${POSTGRES_PASSWORD:-change-me-in-prod}@postgres:5432/{{projectNameSnake}}
+      VOLTRO_SESSION_SECRET: ${VOLTRO_SESSION_SECRET:?must be set for prod compose}
+    ports:
+      - "4000:4000"
+    depends_on:
+      postgres:
+        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-pgdata:

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

@@ -0,0 +1,41 @@
+# {{projectName}} infra docker compose — postgres only.
+#
+# Brought up by `pnpm db:up`. Apps run natively via `pnpm dev` against
+# this. For full-docker dev (apps in containers too), use
+# `pnpm dev:docker` which adds docker-compose.dev.yml on top.
+#
+# Port 5433 (NOT default 5432) so it never clashes with a host
+# Postgres install.
+
+services:
+  postgres:
+    image: postgres:17-alpine
+    container_name: {{projectName}}-postgres
+    restart: unless-stopped
+    environment:
+      POSTGRES_USER: app
+      POSTGRES_PASSWORD: app
+      POSTGRES_DB: {{projectNameSnake}}
+    ports:
+      - "5433:5432"
+    command:
+      - "postgres"
+      # wal_level=logical so CDC subscribers (workflow run mirror,
+      # logical-replication consumers) can subscribe via pgoutput.
+      # Harmless when nothing's subscribing.
+      - "-c"
+      - "wal_level=logical"
+      - "-c"
+      - "max_wal_senders=4"
+      - "-c"
+      - "max_replication_slots=4"
+    volumes:
+      - {{projectName}}-pgdata:/var/lib/postgresql/data
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U app -d {{projectNameSnake}}"]
+      interval: 2s
+      timeout: 2s
+      retries: 10
+
+volumes:
+  {{projectName}}-pgdata:

package/templates/baselines/compose-mariadb/.env.example

@@ -0,0 +1,57 @@
+# Voltro local env — compose-mariadb baseline.
+#
+# The Voltro CLI auto-loads .env from each app dir + every ancestor at
+# boot. Shell exports always override .env values, so CI can set DB_URL
+# via env without touching this file.
+
+# MariaDB connection — points at the mariadb service in docker-compose.yml
+# (port 3307 to avoid clashing with a host MySQL on 3306). Inside the
+# docker network (dev:docker) the host is `mariadb`; native (pnpm dev with
+# pnpm db:up) it's `localhost` on 3307.
+DB_DIALECT=mariadb
+DB_URL=mysql://app:app@localhost:3307/{{projectNameSnake}}
+# Cross-replica real-time via the binlog reader (the compose DB runs with
+# binlog_format=ROW + binlog_row_image=FULL + a replication grant). CDC=0
+# falls back to single-process inline emit.
+CDC=1
+
+# File storage — MinIO locally (S3-compatible). The createbuckets one-shot
+# provisions the bucket; the public /_voltro/storage/:id route serves blobs.
+STORAGE_PROVIDER=minio
+S3_ENDPOINT=http://localhost:9000
+S3_BUCKET={{projectNameSnake}}
+S3_ACCESS_KEY_ID=minioadmin
+S3_SECRET_ACCESS_KEY=minioadmin
+S3_FORCE_PATH_STYLE=1
+
+# HMAC key for signed sessions — REQUIRED by prod:up (no dev fallback).
+VOLTRO_SESSION_SECRET=dev-only-secret-please-rotate-in-prod
+
+# Used by docker-compose.prod.yml — the prod DB uses a different root
+# password from dev (avoids `db:reset` blowing away a prod-shape dataset).
+MARIADB_ROOT_PASSWORD=change-me-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.
+# Enablement is per concern — a bare REDIS_URL is NOT a master switch; each
+# concern reads its own <NAME>_REDIS_URL first, then a shared REDIS_URL.
+
+# @voltro/cache → Redis: a distributed query/result cache. Easiest path:
+# `voltro add redis` uncomments these AND injects a `redis` service into
+# docker-compose.yml; then `docker compose up -d redis` and reboot.
+# 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 the ephemeral cache service `voltro add redis` provisions: 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/compose-mariadb/README.md

@@ -0,0 +1,78 @@
+# Compose baseline — MariaDB + MinIO
+
+Three docker-compose files + two Dockerfiles. **MariaDB** (binlog CDC) +
+**MinIO** (object storage) included. Two flavours: dev with volume-mounted
+HMR, prod with built images. The local mirror of the Helm/MariaDB
+production shape.
+
+## Layout
+
+```
+.
+├── docker/
+│   ├── api.Dockerfile        # multi-stage: deps + builder + prod
+│   ├── web.Dockerfile        # multi-stage: deps + builder + prod
+│   ├── mariadb-init.sql      # grants the app user REPLICATION (CDC reader)
+│   └── .dockerignore
+├── docker-compose.yml        # mariadb + minio — the "infra" file
+├── docker-compose.dev.yml    # mariadb + minio + apps in dev mode
+└── docker-compose.prod.yml   # mariadb + minio + apps in prod (built images)
+```
+
+The MariaDB service runs with `binlog_format=ROW` + `binlog_row_image=FULL`
+and a replication grant — Voltro's CDC reader tails the binary log to fan
+real-time subscriptions out across replicas (the binlog IS the message
+bus). MinIO provides S3-compatible object storage for the file-storage
+primitive; the `createbuckets` one-shot provisions the app bucket.
+
+## Common flows
+
+### Daily dev — fastest
+
+```sh
+pnpm db:up      # boot mariadb + minio (+ create the bucket)
+pnpm dev        # turbo run dev, native node, HMR <50ms
+```
+
+### Daily dev — full-docker (slower HMR but zero host install)
+
+```sh
+pnpm dev:docker        # boots mariadb + minio + all apps in containers
+pnpm dev:docker:down   # stop everything
+```
+
+### Production smoke-test on localhost
+
+```sh
+pnpm prod:build      # build all images (slow first run, ~5 min)
+pnpm prod:up         # boot the prod stack
+pnpm prod:down       # tear down
+```
+
+## When to add apps
+
+The shipped compose files cover ONE api + ONE web by default. As you
+add apps to `apps/`, mirror the pattern in both `docker-compose.dev.yml`
+and `docker-compose.prod.yml`: copy a service block, change its
+`working_dir` / `APP_PATH` / port.
+
+A future `voltro baseline sync` will auto-regenerate the service
+blocks from your `project.json` / `app.config.ts` files. Until then,
+hand-edit.
+
+## What's NOT in here
+
+- No CI configs (GitHub Actions / GitLab CI). Each provider's syntax
+  is different; we don't pick a winner.
+- No reverse proxy (Traefik / nginx / Caddy). If you need one in
+  prod, add it as a service in `docker-compose.prod.yml`.
+- No Redis, S3-emulator, or other infra. Add as needed.
+
+## Switching baselines
+
+`voltro baseline set helm` → swaps to Helm chart + Kustomize overlays.
+`voltro baseline set bare` → removes docker-compose entirely.
+
+Either switch backs up the current docker-compose files + Dockerfiles
+to `.voltro-baseline-backup/<timestamp>/`. Application code is never
+touched.

package/templates/baselines/compose-mariadb/baseline.json

@@ -0,0 +1,51 @@
+{
+  "id": "compose-mariadb",
+  "displayName": "Docker Compose (MariaDB + MinIO)",
+  "summary": "Full stack via docker-compose: MariaDB with binlog CDC (ROW) + MinIO object storage. The local-dev shape for Voltro apps that deploy to MariaDB / K8s.",
+  "tags": ["docker", "compose", "mariadb", "cdc", "minio", "storage"],
+  "recommendedFor": "Apps targeting MariaDB (company DB) with real-time CDC + file storage; the local mirror of the Helm baseline.",
+  "tradeoffs": {
+    "pros": [
+      "Boots MariaDB (binlog ROW) + MinIO with one `pnpm db:up` — CDC works single-node",
+      "Local mirror of the K8s/MariaDB production shape (no surprises at deploy)",
+      "Object storage (avatars, AI blobs) works locally via MinIO",
+      "Zero-host-install: docker + git is all you need"
+    ],
+    "cons": [
+      "HMR through volumes (dev:docker) is slower than native (200-2000ms, esp. macOS)",
+      "MariaDB binlog retention grows on disk; tune binlog-expire-logs-seconds for long-lived volumes",
+      "Docker Desktop adds ~3GB memory overhead on macOS/Windows"
+    ]
+  },
+  "files": [
+    ".env.example",
+    "docker/api.Dockerfile",
+    "docker/web.Dockerfile",
+    "docker/dev.Dockerfile",
+    "docker/.dockerignore",
+    "docker/mariadb-init.sql",
+    "docker-compose.yml",
+    "docker-compose.dev.yml",
+    "docker-compose.prod.yml"
+  ],
+  "packageJsonScripts": {
+    "dev":             "turbo run dev",
+    "dev:hybrid":      "docker compose up -d --wait mariadb minio && docker compose up -d createbuckets && turbo run dev",
+    "dev:docker":      "HOST_UID=$(id -u) HOST_GID=$(id -g) docker compose -f docker-compose.dev.yml up",
+    "dev:docker:bg":   "HOST_UID=$(id -u) HOST_GID=$(id -g) docker compose -f docker-compose.dev.yml up -d",
+    "dev:docker:down": "docker compose -f docker-compose.dev.yml down",
+    "dev:docker:logs": "docker compose -f docker-compose.dev.yml logs -f",
+    "build":           "turbo run build",
+    "test":            "turbo run test",
+    "typecheck":       "turbo run typecheck",
+    "db:up":           "docker compose up -d --wait mariadb minio && docker compose up -d createbuckets",
+    "db:down":         "docker compose stop mariadb minio",
+    "db:reset":        "docker compose down -v && docker compose up -d --wait mariadb minio && docker compose up -d createbuckets",
+    "db:logs":         "docker compose logs -f mariadb",
+    "db:sql":          "docker compose exec mariadb mariadb -uapp -papp {{projectNameSnake}}",
+    "prod:build":      "docker compose -f docker-compose.prod.yml build",
+    "prod:up":         "docker compose -f docker-compose.prod.yml up -d",
+    "prod:down":       "docker compose -f docker-compose.prod.yml down",
+    "prod:logs":       "docker compose -f docker-compose.prod.yml logs -f"
+  }
+}

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

@@ -0,0 +1,38 @@
+# Build context excludes — keep image size sane.
+#
+# Most of these are obvious noise. Customize per project if you
+# have additional generated dirs to exclude.
+
+**/node_modules
+**/dist
+**/.turbo
+**/.next
+**/.vite
+**/.cache
+**/coverage
+
+**/.env
+**/.env.local
+**/.env.*.local
+**/.voltro
+**/.voltro-baseline-backup
+
+**/.git
+**/.gitignore.local
+
+**/.vscode
+**/.idea
+**/*.swp
+**/*.swo
+
+**/*.log
+**/npm-debug.log*
+**/yarn-debug.log*
+**/yarn-error.log*
+
+**/.DS_Store
+**/Thumbs.db
+
+**/Dockerfile*
+**/docker-compose*.yml
+**/.dockerignore

package/templates/baselines/compose-mariadb/docker/api.Dockerfile

@@ -0,0 +1,57 @@
+# API service Dockerfile for {{projectName}}'s Node-based api apps.
+#
+# Build context = project root (where pnpm-workspace.yaml lives).
+# The `.dockerignore` next to this file aggressively excludes noise.
+#
+# Build args:
+#   APP_PATH  — path relative to context where the api lives.
+#               e.g. apps/{{projectName}}/api
+#
+# Targets:
+#   prod  — production image (this file's only target; dev uses
+#           node:24-alpine directly via docker-compose.dev.yml so
+#           code mounts work without an image-build step).
+#
+# Build:
+#   docker build \
+#     -f docker/api.Dockerfile \
+#     --build-arg APP_PATH=apps/{{projectName}}/api \
+#     -t {{projectName}}-api:latest \
+#     .
+
+ARG NODE_VERSION=24-alpine
+ARG PNPM_VERSION=10.25.0
+ARG APP_PATH=apps/{{projectName}}/api
+
+# ---------- deps stage ----------
+FROM node:${NODE_VERSION} AS deps
+ARG PNPM_VERSION
+RUN corepack enable && corepack prepare pnpm@${PNPM_VERSION} --activate
+WORKDIR /workspace
+
+# Copy ONLY what pnpm install needs — lockfile + workspace manifests.
+COPY pnpm-lock.yaml pnpm-workspace.yaml package.json ./
+COPY apps apps
+COPY packages packages
+
+RUN pnpm install --frozen-lockfile
+
+# ---------- builder stage ----------
+FROM deps AS builder
+ARG APP_PATH
+WORKDIR /workspace/${APP_PATH}
+RUN pnpm voltro codegen . || true
+
+# ---------- prod runner ----------
+FROM node:${NODE_VERSION} AS prod
+ARG PNPM_VERSION
+ARG APP_PATH
+RUN corepack enable && corepack prepare pnpm@${PNPM_VERSION} --activate
+WORKDIR /workspace
+
+COPY --from=builder /workspace /workspace
+
+WORKDIR /workspace/${APP_PATH}
+EXPOSE 4000
+ENV NODE_ENV=production
+CMD ["pnpm", "voltro", "start", "."]

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

@@ -0,0 +1,35 @@
+# Dev runtime image for {{projectName}}'s node/vite services.
+#
+# Why this exists (vs `image: node:24-alpine` directly in compose):
+#
+# Compose's `user: "${HOST_UID}:${HOST_GID}"` directive runs the
+# container process as the host's UID/GID so files written into the
+# bind-mounted workspace land owned by the host user, not root.
+# That kills the "root-owned .framework/.vite/deps blocks native vite"
+# bug that bites every dev who alternates between full-docker and
+# native pnpm dev.
+#
+# But it also means:
+#   - The container has no `/etc/passwd` entry for that numeric UID,
+#     so HOME resolves to `/` (read-only for non-root).
+#   - `corepack enable` writes to `/usr/local/bin/` (root-owned in the
+#     stock node image), which a non-root container can't do.
+#
+# So we PREBAKE pnpm here as root at build time. /usr/local/bin/pnpm
+# becomes world-executable (mode 755) → the non-root runtime user can
+# exec it. HOME=/tmp gives pnpm/npm a writable home for state files.
+#
+# Build:
+#   docker build -f docker/dev.Dockerfile -t {{projectName}}-dev .
+# (compose's `build:` does this automatically on first `up`)
+
+FROM node:24-alpine
+
+RUN corepack enable && corepack prepare pnpm@10.25.0 --activate
+
+ENV HOME=/tmp
+ENV PATH=/tmp/.local/bin:$PATH
+
+# Don't pin a USER directive here — that would FREEZE the image to a
+# specific UID. Compose's `user: "${HOST_UID}:${HOST_GID}"` is the
+# right place to do that, dynamic per-host.

package/templates/baselines/compose-mariadb/docker/mariadb-init.sql

@@ -0,0 +1,6 @@
+-- Runs once on first DB init (mounted into /docker-entrypoint-initdb.d/).
+-- The MARIADB_USER ('app') is created by the image with full grants on the
+-- app database; Voltro's binlog CDC reader ALSO needs replication grants to
+-- tail the binary log.
+GRANT REPLICATION SLAVE, REPLICATION CLIENT ON *.* TO 'app'@'%';
+FLUSH PRIVILEGES;

package/templates/baselines/compose-mariadb/docker/web.Dockerfile

@@ -0,0 +1,59 @@
+# Web (Vite) Dockerfile for {{projectName}}'s React apps.
+#
+# Build context = project root (where pnpm-workspace.yaml lives).
+# The `.dockerignore` next to this file aggressively excludes noise.
+#
+# Build args:
+#   APP_PATH  — path relative to context where the web app lives.
+#               e.g. apps/{{projectName}}/web
+#   APP_PORT  — the port the app's `voltro start` listens on.
+#               Must match the app's app.config.ts `port` field.
+#
+# Targets:
+#   prod  — production image (`voltro build .` then `voltro start .`)
+#
+# Build:
+#   docker build \
+#     -f docker/web.Dockerfile \
+#     --build-arg APP_PATH=apps/{{projectName}}/web \
+#     --build-arg APP_PORT=5173 \
+#     -t {{projectName}}-web:latest \
+#     .
+
+ARG NODE_VERSION=24-alpine
+ARG PNPM_VERSION=10.25.0
+ARG APP_PATH=apps/{{projectName}}/web
+ARG APP_PORT=5173
+
+# ---------- deps stage ----------
+FROM node:${NODE_VERSION} AS deps
+ARG PNPM_VERSION
+RUN corepack enable && corepack prepare pnpm@${PNPM_VERSION} --activate
+WORKDIR /workspace
+
+COPY pnpm-lock.yaml pnpm-workspace.yaml package.json ./
+COPY apps apps
+COPY packages packages
+
+RUN pnpm install --frozen-lockfile
+
+# ---------- builder stage ----------
+FROM deps AS builder
+ARG APP_PATH
+WORKDIR /workspace/${APP_PATH}
+RUN pnpm voltro build .
+
+# ---------- prod runner ----------
+FROM node:${NODE_VERSION} AS prod
+ARG PNPM_VERSION
+ARG APP_PATH
+ARG APP_PORT
+RUN corepack enable && corepack prepare pnpm@${PNPM_VERSION} --activate
+WORKDIR /workspace
+
+COPY --from=builder /workspace /workspace
+
+WORKDIR /workspace/${APP_PATH}
+EXPOSE ${APP_PORT}
+ENV NODE_ENV=production
+CMD ["pnpm", "voltro", "start", "."]