kampodra 0.8.4 → 0.8.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kampodra",
-  "version": "0.8.4",
+  "version": "0.8.7",
   "description": "Registry-free deployment CLI for single-VM container stacks over SSH (Podman + kamal-proxy)",
   "license": "AGPL-3.0",
   "type": "module",
@@ -8,10 +8,10 @@
     "kampodra": "bin/kampodra.js"
   },
   "optionalDependencies": {
-    "@kampodra/darwin-arm64": "0.8.4",
-    "@kampodra/darwin-x64": "0.8.4",
-    "@kampodra/linux-arm64": "0.8.4",
-    "@kampodra/linux-x64": "0.8.4"
+    "@kampodra/darwin-arm64": "0.8.7",
+    "@kampodra/darwin-x64": "0.8.7",
+    "@kampodra/linux-arm64": "0.8.7",
+    "@kampodra/linux-x64": "0.8.7"
   },
   "engines": {
     "node": ">=20"

package/skills/kampodra/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: kampodra
-description: "Operates the kampodra CLI, a kamal-alternative that deploys containers or binaries to Linux VMs over SSH with podman and kamal-proxy — no registry in the image path, zero-downtime by default. Use when deploying or rolling back a release, running the standby-update bluegreen flow (deploy to the idle color then flip), recovering an interrupted rolling deploy, reading deploy logs/status, pushing or diffing remote env files, generating env from a schema, managing instance profiles, listing or verifying backups, planning a restore, managing DNS records on OCI or GCP, staging golden images, running tenant database migrations, sampling VM metrics, or preparing and wiping VMs. Triggers: deploy, rollback, podman, kamal-proxy, SSH, env, metrics, backup, DNS, gcp, gcloud, oci, bluegreen, flip, migrate, VM, Alpine."
+description: "Operates the kampodra CLI, a kamal-alternative that deploys containers or binaries to Linux VMs over SSH with podman and kamal-proxy — no registry in the image path, zero-downtime by default. Use when deploying or rolling back a release, running the standby-update bluegreen flow (deploy to the idle color then flip), recovering an interrupted rolling deploy, reading deploy logs/status, pushing or diffing remote env files, generating env from a schema, managing instance profiles, listing or verifying backups, planning a restore, managing DNS records on OCI or GCP, staging golden images, running tenant database migrations, sampling VM metrics, preparing or wiping VMs, or running read-only database queries and snapshots (sqlite, MariaDB, self-hosted libsql/sqld). Triggers: deploy, rollback, podman, kamal-proxy, SSH, env, metrics, backup, DNS, gcp, gcloud, oci, bluegreen, flip, migrate, VM, Alpine, db query, db snapshot, libsql, sqld, mariadb, sqlite."
 license: AGPL-3.0
 compatibility: Requires podman, ssh, and git locally; the target VM needs a Linux userland (Alpine or Ubuntu 24.04) with podman and kamal-proxy (vm-prepare installs them). Cloud families authenticate through the provider CLI itself (oci or gcloud).
 metadata:
@@ -90,6 +90,7 @@ A leftover shadow must be converged before the next `--rolling` deploy. `--drain
 | Operation | Behavior | Guard |
 |---|---|---|
 | `vm-wipe` | Stops/disables services, removes project containers, prunes images, deletes env/stamp/state | `--yes` REQUIRED; `--keep-data` spares the data dir; `--force` overrides a services-mismatch refusal (wrong host?) |
+| `vm gc --apply` | Deletes ONLY stale scratch/scripts/residues from the typed sweep inventory | Dry run by default; hard-coded never-touch allowlists (tenant data, live chains, kampodra helpers, OS, build contexts, owner decisions); podman strictly report-only; in-use candidates blocked |
 | `backup restore-plan <object>` | PRINTS the documented recovery sequence | Never executes anything |
 | `backup verify <file>` | Read-only: uploads to VM scratch files and runs the VM's `restore-verify` | Never writes into the data dir |
 | `deploy prune` | Removes old sha-tagged images (keeps running + ts-rollback + newest N) | `--dry-run` prints exact commands first |
@@ -97,6 +98,51 @@ A leftover shadow must be converged before the next `--rolling` deploy. `--drain
 | `env push` | Overwrites the remote env file atomically | Preview first with `env diff <local-file>` (exit 1 = differs) |
 | `vm-prepare` | Mutates a bare host (packages, sshd, services) | Idempotent; safe to re-run |
 
+## Read-only database access (db)
+
+`kampodra db query` (one SELECT/WITH → rows on stdout) and
+`kampodra db snapshot` (verified consistent copy, 0600) over ssh, three
+engines behind `--engine auto` (flag > the VM env file's
+KAMPODRA_DB_ENGINE > file magic):
+
+- **sqlite** — `--db` is the file's path; rows as flat JSON; snapshot via
+  `sqlite3 .backup` (consistent).
+- **mariadb** — `--db` is the schema NAME; creds ride the VM env file
+  (KAMPODRA_DB_NAME/HOST/USER/PASSWORD via `kampodra env set`), staged to
+  a 0600 defaults file, never argv; snapshot = mariadb-dump
+  --single-transaction with a "Dump completed" tail gate. Prefer a
+  read-only role (GRANT SELECT) for agent queries — `db grant-ro`
+  provisions it (mariadb executes; postgres prints the SQL). Podman
+  container deployments (the estate's shape): no host client needed —
+  tools run via `podman exec` in-container, and snapshots take the
+  PHYSICAL form (in-container mariabackup → prepare → tar, gated on the
+  control files; restore with mariabackup --copy-back).
+- **postgres** — same env-file contract as mariadb; PGPASSFILE staged
+  0600; pg_dump MVCC-consistent with a completeness tail gate.
+- **libsql (self-hosted sqld)** — no --db needed; KAMPODRA_DB_URL
+  (default localhost:8080) + optional KAMPODRA_DB_TOKEN, staged to a 0600
+  header file; rows as flat JSON (same shape as sqlite); snapshot needs
+  KAMPODRA_DB_PATH and gates on PRAGMA integrity_check.
+
+Server engines on their own VM: `--db-host` / profile `dbHost` moves the
+flows' ssh to the DB VM (its env file carries the creds). TSV engines
+emit string values (batch text has no types); file engines emit typed
+JSON.
+
+`kampodra db grant-ro --db <schema>` provisions the read-only role:
+mariadb executes end-to-end (random password, env keys written on the
+VM, password never printed); `--engine postgres` prints the ready SQL.
+
+The gate rejects non-SELECT/WITH statements (exit 2) BEFORE any ssh on
+every engine — a rejected statement costs zero round-trips.
+
+```
+kampodra db query --db /data/root.db --sql "SELECT count(*) FROM org" --profile prod
+kampodra db query --db esellar --sql "SELECT id, total FROM pos_order LIMIT 5"   # mariadb, after env set
+kampodra db snapshot --db esellar --out ./esellar.sql
+kampodra db snapshot --out ./app.db                                              # libsql, after env set
+```
+
 ## Gotchas
 
 - Defaults are GENERIC placeholders (`app`, `/etc/kampodra/env`, `app-backups`, `/up`), not your app's names — commit a `kampodra.json` before the first deploy against a new tree, or check `config print`.

package/skills/kampodra/references/commands.md

@@ -17,6 +17,7 @@ CLI source (`internal/command/*.go`). When this file and `kampodra <command>
 - [backup](#backup) (list / download / verify / restore-plan)
 - [vm-prepare](#vm-prepare)
 - [vm-wipe](#vm-wipe)
+- [vm gc](#vm-gc)
 - [metrics](#metrics)
 - [dns](#dns) (records / add / rm)
 - [migrate](#migrate)
@@ -355,6 +356,33 @@ running, it refuses (`--force` to mean it — wrong host?). Individual step
 failures are tolerated and reported, not fatal.
 Example: `kampodra vm-wipe --profile prod --yes --keep-data`
 
+## vm gc
+
+Dry-run-by-default VM garbage sweep: a typed inventory of every host
+artifact (scratch / stale-script / residue / kampodra-helper / os-session
+/ os / infra / tenant-data / live / owner-decision / unknown), with
+`--apply` deleting ONLY the stale classes. Built so agents never hand-roll
+`find | rm` sweeps over raw ssh again — the never-touch allowlists are
+enforced in code, twice (classification + per-command validation).
+
+| Flag | Type | Default |
+|---|---|---|
+| `--apply` | bool | `false` — delete the stale classes found by the sweep |
+| `--host` | string | `""` |
+| `--profile` | string | `""` |
+| `--ssh-key` | string | `""` |
+
+- NEVER touched: OS paths + podman storage, the live artifact/web/backup
+  chains, kampodra's own helpers (`/tmp/kampodra-*`), OS session dirs,
+  live build contexts (scratch dirs holding a Dockerfile), cutover db
+  snapshots beside the data dir, `/root` pre-op safety snapshots.
+- Tenant data routes from the project's `dataDir` (zero knowledge fails
+  closed to report-only); podman is strictly report-only; candidates in
+  use by a live process or container bind mount are BLOCKED.
+- `/opt` and `/home`: unrecognized content is report-only; only stale
+  `.sh` scripts are deletable there.
+Example: `kampodra vm gc --profile prod --apply`
+
 ## metrics
 
 One-shot VM snapshot over SSH (load, memory, disk breakdown, containers, top
@@ -415,8 +443,11 @@ Tenant db migrations over SSH, applied THROUGH the repo checkout ON the VM
 (the app's own script, path from the `migrateScript` config — default
 `scripts/migrate-db.ts`; no parallel implementation; runs via `pnpm exec
 tsx`). Order: root.db first
-(`root/root.db` preferred, legacy flat `root.db` honored), then `tenant_*.db`
-sorted, bounded-parallel. Preconditions are probed in one round-trip and fail
+(`root/root.db` preferred, legacy flat `root.db` honored), then the support
++ billing class dbs (`support/support.db`, `billing/billing.db` — their own
+`-dir` pairings in binary mode), then `tenant_*.db`
+sorted, bounded-parallel. A db file matching no known class is an explicit
+warned skip. Preconditions are probed in one round-trip and fail
 closed: repo root (must contain the migrate script), pnpm, tenant data dir.
 
 | Flag | Type | Default |