vela 0.10.5 → 0.10.7

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "vela",
-	"version": "0.10.5",
+	"version": "0.10.7",
 	"type": "module",
 	"description": "A CLI for creating and updating SvelteKit projects",
 	"license": "MIT",

package/templates/minimal/_gitignore

@@ -28,3 +28,5 @@ vite.config.ts.timestamp-*
 !/data/seeds
 !/data/hooks
 
+# Backups
+/backups

package/templates/minimal/data/README.md

@@ -0,0 +1,25 @@
+# data
+
+This app's state, and the only directory in the project that outlives a release.
+
+PocketBase keeps `data.db` and `storage/` here. Anything else the app writes —
+its own SQLite database, uploaded files — belongs here too, and nowhere else. A
+path built from `process.cwd()` resolves inside the release directory once the
+app is on a server, which is where the next deploy leaves it behind and the
+pruner eventually deletes it.
+
+Ask for the directory rather than working it out:
+
+```ts
+import { dataPath } from '@velastack/kit/server';
+
+const db = new Database(dataPath('app.sqlite'));
+```
+
+`vela` sets `VELA_DATA_DIR` in every context — `vela dev`, `vela build`, and the
+environment it writes on each deploy — so that one call answers `<project>/data`
+here and `/var/lib/vela/apps/<id>/shared/pb_data` on a server.
+
+Because it is PocketBase's own directory, `vela backup` captures everything in
+it and `vela restore` replaces it. `backups/` is the exception: PocketBase
+leaves that out of the archives it writes.

package/templates/minimal/package.template.json

@@ -23,7 +23,7 @@
 		"@tailwindcss/typography": "^0.5.19",
 		"@tailwindcss/vite": "^4.3.3",
 		"@types/supertest": "^6.0.3",
-		"@velastack/kit": "^0.2.0",
+		"@velastack/kit": "^0.3.0",
 		"@velastack/pocketbase": "^0.2.2",
 		"clsx": "^2.1.1",
 		"formsnap": "^2.0.1",

package/templates/server/apply.sh

@@ -63,8 +63,24 @@ PB_UNIT=$(unit_pb "$INSTANCE")
 mkdir -p "$APP"/{releases,shared,bin,deps} "$APP/shared/pb_data"
 mkdir -p "$ETC"
 chmod 0700 "$ETC"
-chown -R "$VELA_USER:$VELA_USER" "$APP"
-chown "$VELA_USER:$VELA_USER" "$RELEASE_DIR"
+
+# Only the directories just created need their ownership set, and only at the
+# top level: everything below pb_data is written by PocketBase as $VELA_USER
+# already. Recursing here would walk every uploaded file on every deploy, which
+# makes deploy time grow with the size of the app's storage forever.
+chown "$VELA_USER:$VELA_USER" \
+	"$APP" "$APP/releases" "$APP/shared" "$APP/shared/pb_data" "$APP/bin" "$APP/deps"
+# The release is the exception - rsync uploaded it as whoever we ssh'd in as.
+chown -R "$VELA_USER:$VELA_USER" "$RELEASE_DIR"
+
+# A pb_data the app cannot write is a dead instance, and it fails as an opaque
+# 500 rather than anything that names a cause. This is what the blanket recurse
+# above used to paper over; checking costs one stat, repairing costs a walk that
+# now happens only when something is actually wrong.
+if ! runuser -u "$VELA_USER" -- test -w "$APP/shared/pb_data"; then
+	log "repairing ownership under shared/"
+	chown -R "$VELA_USER:$VELA_USER" "$APP/shared"
+fi
 
 # ---------------------------------------------------------------- ports & env
 
@@ -83,6 +99,23 @@ fi
 # Nothing here reads or rewrites that file.
 [ -f "$ETC/env" ] || { : > "$ETC/env"; chmod 0600 "$ETC/env"; chown root:root "$ETC/env"; }
 
+# Where this app keeps state that has to outlive a release.
+#
+# An app that works this out from its own working directory puts it inside the
+# release, which is the one place it cannot survive: `current` moves on the next
+# deploy and the pruner deletes what it left behind. An instance with a database
+# shares PocketBase's directory, so anything the app writes there is inside the
+# archives `vela backup` takes and inside the directory `vela restore` swaps. An
+# instance without one gets a directory of its own, which nothing backs up -
+# there is no database to back it up alongside.
+if [ "$BACKEND" = "1" ]; then
+	APP_DATA_DIR="$APP/shared/pb_data"
+else
+	APP_DATA_DIR="$APP/shared/data"
+	mkdir -p "$APP_DATA_DIR"
+	chown "$VELA_USER:$VELA_USER" "$APP_DATA_DIR"
+fi
+
 runtime_tmp=$(mktemp "$ETC/.runtime.XXXXXX")
 {
 	printf '# Generated by vela on each deploy. Edit /etc/vela/apps/%s/env instead.\n' "$INSTANCE"
@@ -92,6 +125,7 @@ runtime_tmp=$(mktemp "$ETC/.runtime.XXXXXX")
 	printf 'ORIGIN=%s\n' "$ORIGIN"
 	printf 'PB_PORT=%s\n' "$PB_PORT"
 	printf 'POCKETBASE_URL=http://127.0.0.1:%s\n' "$PB_PORT"
+	printf 'VELA_DATA_DIR=%s\n' "$APP_DATA_DIR"
 	printf 'VELA_APP_ID=%s\n' "$APP_ID"
 	printf 'VELA_APP_NAME=%s\n' "$APP_NAME"
 	printf 'VELA_ENV=%s\n' "$ENV_TAG"
@@ -228,30 +262,13 @@ if [ "$BACKEND" = "1" ]; then
 		SU_CREATED=1
 	fi
 
-	# The password reaches PocketBase as an argument, so the upsert runs only on
-	# the deploys that need it rather than on every one.
-	SU_STAMP="$ETC/.superuser"
-	SU_FINGERPRINT=$(printf '%s\n%s' "$SU_EMAIL" "$SU_PASSWORD" | sha256sum | cut -d' ' -f1)
-	if [ "$SU_CREATED" = "1" ] || [ "$(cat "$SU_STAMP" 2>/dev/null || true)" != "$SU_FINGERPRINT" ]; then
-		if [ "$SU_CREATED" = "1" ]; then
-			log "creating the PocketBase superuser"
-		else
-			log "updating the PocketBase superuser"
-		fi
-		runuser -u "$VELA_USER" -- "$APP/bin/pocketbase" \
-			--dir "$APP/shared/pb_data" \
-			superuser upsert "$SU_EMAIL" "$SU_PASSWORD" >&2 \
-			|| die "could not create the PocketBase superuser"
-
-		# Recorded only once the database holds the account, so a failure above
-		# leaves nothing behind and the next deploy simply tries again.
-		if [ "$SU_CREATED" = "1" ]; then
-			env_file_append "$ETC/env" POCKETBASE_SUPERUSER_EMAIL "$SU_EMAIL"
-			env_file_append "$ETC/env" POCKETBASE_SUPERUSER_PASSWORD "$SU_PASSWORD"
-		fi
-		printf '%s\n' "$SU_FINGERPRINT" > "$SU_STAMP"
-		chmod 0600 "$SU_STAMP"
-		chown root:root "$SU_STAMP"
+	reconcile_superuser "$APP" "$ETC" "$SU_EMAIL" "$SU_PASSWORD"
+
+	# Written only once the database holds the account, so a failure above leaves
+	# nothing behind and the next deploy simply tries again.
+	if [ "$SU_CREATED" = "1" ]; then
+		env_file_append "$ETC/env" POCKETBASE_SUPERUSER_EMAIL "$SU_EMAIL"
+		env_file_append "$ETC/env" POCKETBASE_SUPERUSER_PASSWORD "$SU_PASSWORD"
 	fi
 fi
 
@@ -274,6 +291,25 @@ if [ "$BACKEND" = "1" ]; then
 	systemctl restart "$PB_UNIT"
 	wait_for_http "http://127.0.0.1:$PB_PORT/api/health" 60 0.5 \
 		|| die "PocketBase did not become healthy - journalctl -u $PB_UNIT"
+
+	# Answering on the port is not the same as agreeing with $ETC/env, and a
+	# disagreement shows up as every render 401ing rather than as a failed start.
+	#
+	# The fingerprint above cannot see a database that was replaced underneath
+	# an env file that did not change, so a first failure is repaired rather than
+	# reported: force the upsert and ask again. Only a second failure is real.
+	if ! assert_superuser_auth "$PB_PORT" "$SU_EMAIL" "$SU_PASSWORD"; then
+		log "the database disagrees with this instance's credentials - repairing"
+		# Stopped for the upsert: it opens the same SQLite file directly, and a
+		# running PocketBase is one writer too many to reason about.
+		systemctl stop "$PB_UNIT" >/dev/null 2>&1 || true
+		reconcile_superuser "$APP" "$ETC" "$SU_EMAIL" "$SU_PASSWORD" --force
+		systemctl start "$PB_UNIT"
+		wait_for_http "http://127.0.0.1:$PB_PORT/api/health" 60 0.5 \
+			|| die "PocketBase did not come back after the credential repair"
+		assert_superuser_auth "$PB_PORT" "$SU_EMAIL" "$SU_PASSWORD" \
+			|| die "PocketBase does not accept this instance's superuser credentials"
+	fi
 fi
 
 log "starting app on 127.0.0.1:$WEB_PORT"

package/templates/server/lib.sh

@@ -19,6 +19,14 @@ require_provisioned() {
 	[ -f "$VELA_ETC/provisioned" ] || die "server is not provisioned - run 'vela provision' first"
 }
 
+# Refuse on a frontend-only instance. Absent state is treated as having one, so
+# this only ever fires on an instance that was deployed with --backend 0.
+require_backend() {
+	local instance=$1
+	[ "$(state_get "$instance" backend 2>/dev/null || echo true)" = "true" ] \
+		|| die "$instance has no database - there is nothing to back up or restore"
+}
+
 # Read a top-level key out of an instance's state file.
 state_get() {
 	local instance=$1 key=$2 file
@@ -164,3 +172,59 @@ env_file_append() {
 random_secret() {
 	head -c 24 /dev/urandom | od -An -tx1 | tr -d ' \n'
 }
+
+# Make the instance's database agree with the credentials in its env file.
+#
+# The app authenticates to its own PocketBase as a superuser on every render, so
+# the two have to match or every request answers 401. `$ETC/env` is the source of
+# truth: this pushes whatever it holds into the database and records a
+# fingerprint of it, which is what lets an ordinary deploy skip the upsert when
+# nothing has moved. A caller that replaced the database underneath the env file
+# passes --force, because the fingerprint alone cannot see that.
+#
+# usage: reconcile_superuser <app_dir> <etc_dir> <email> <password> [--force]
+reconcile_superuser() {
+	local app=$1 etc=$2 email=$3 password=$4 force=${5:-}
+	local stamp="$etc/.superuser" fingerprint
+	fingerprint=$(printf '%s\n%s' "$email" "$password" | sha256sum | cut -d' ' -f1)
+
+	if [ "$force" != "--force" ] && [ "$(cat "$stamp" 2>/dev/null || true)" = "$fingerprint" ]; then
+		return 0
+	fi
+
+	# The stamp is written only after a successful upsert, so its absence is what
+	# distinguishes a first account from a changed one.
+	if [ -f "$stamp" ]; then
+		log "updating the PocketBase superuser"
+	else
+		log "creating the PocketBase superuser"
+	fi
+
+	# The password reaches PocketBase as an argument, which is why this runs only
+	# on the deploys that need it rather than on every one.
+	runuser -u "$VELA_USER" -- "$app/bin/pocketbase" \
+		--dir "$app/shared/pb_data" \
+		superuser upsert "$email" "$password" >&2 \
+		|| die "could not write the PocketBase superuser"
+
+	# Recorded only once the database holds the account, so a failure above
+	# leaves nothing behind and the next deploy simply tries again.
+	printf '%s\n' "$fingerprint" > "$stamp"
+	chmod 0600 "$stamp"
+	chown root:root "$stamp"
+}
+
+# Prove the app's own credentials actually sign in to its database.
+#
+# `wait_for_http` accepts 4xx as healthy, so a PocketBase whose database no
+# longer matches `$ETC/env` sails through the health gate and then answers every
+# render with a 401. Only an actual login catches that. The password travels
+# through the environment rather than argv, so it never appears in `ps`.
+assert_superuser_auth() {
+	local port=$1 email=$2 password=$3
+	VELA_SU_EMAIL=$email VELA_SU_PASSWORD=$password \
+		jq -nc '{identity: env.VELA_SU_EMAIL, password: env.VELA_SU_PASSWORD}' \
+		| curl -fsS -o /dev/null --max-time 10 \
+			-X POST -H 'content-type: application/json' --data-binary @- \
+			"http://127.0.0.1:$port/api/collections/_superusers/auth-with-password"
+}

package/templates/server/restore.sh

@@ -0,0 +1,269 @@
+#!/usr/bin/env bash
+#
+# Replace one instance's database and uploads from a backup archive.
+#
+# This is the offline counterpart of PocketBase's own restore endpoint, which is
+# not usable here for two reasons: it answers 204 and then does the work in a
+# detached goroutine, so a failure is invisible to whoever asked for it; and it
+# leaves the database holding whatever superuser the archive captured, while
+# /etc/vela/apps/<instance>/env still holds the one the app signs in with on
+# every render. Reconciling those is the whole reason this script exists.
+#
+# The old pb_data is renamed, never deleted. It is the only undo.
+#
+# usage: restore.sh <instance> --archive <path> [options]
+set -Eeuo pipefail
+
+SCRIPT_DIR=$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)
+# shellcheck source=lib.sh
+. "$SCRIPT_DIR/lib.sh"
+
+require_provisioned
+[ "$(id -u)" -eq 0 ] || die "restore must run as root"
+
+INSTANCE=${1:-}; shift || true
+[ -n "$INSTANCE" ] || die "usage: restore.sh <instance> --archive <path> [options]"
+
+ARCHIVE=""
+MIGRATE=1
+KEEP_PREVIOUS=1
+CLEANUP_ARCHIVE=0
+HEALTH_PATH=""
+
+while [ $# -gt 0 ]; do
+	case "$1" in
+		--archive) ARCHIVE=$2; shift 2 ;;
+		--no-migrate) MIGRATE=0; shift ;;
+		--keep-previous) KEEP_PREVIOUS=$2; shift 2 ;;
+		--cleanup-archive) CLEANUP_ARCHIVE=1; shift ;;
+		--health-path) HEALTH_PATH=$2; shift 2 ;;
+		*) die "unknown argument: $1" ;;
+	esac
+done
+
+[ -n "$ARCHIVE" ] || die "--archive is required"
+
+# Commands that drop to the app user inherit this working directory, and the
+# directory the CLI happened to invoke from is usually one it cannot stat.
+cd "$VELA_ROOT"
+
+require_backend "$INSTANCE"
+
+APP=$(app_dir "$INSTANCE")
+ETC=$(etc_dir "$INSTANCE")
+PB_DATA="$APP/shared/pb_data"
+WEB_UNIT=$(unit_web "$INSTANCE")
+PB_UNIT=$(unit_pb "$INSTANCE")
+STAMP=$(date -u +%Y%m%dT%H%M%SZ)
+PREVIOUS_DIR="$APP/shared/pb_data.pre-restore-$STAMP"
+
+[ -d "$APP" ] || die "$INSTANCE is not deployed on this server"
+[ -f "$ARCHIVE" ] || die "no archive at $ARCHIVE"
+
+[ -n "$HEALTH_PATH" ] || HEALTH_PATH=$(state_get "$INSTANCE" healthCheckPath 2>/dev/null || echo /)
+
+PORTS=$(allocate_ports "$INSTANCE")
+WEB_PORT=$(printf '%s' "$PORTS" | jq -r .web)
+PB_PORT=$(printf '%s' "$PORTS" | jq -r .pb)
+
+# Two restores at once would each move the other's pb_data aside.
+exec 9>"$APP/.restore.lock"
+flock -n 9 || die "another restore is already running for $INSTANCE"
+
+# ---------------------------------------------------------------- preflight
+#
+# Everything that can be checked before a service stops is checked before a
+# service stops. A restore that fails here has changed nothing at all.
+
+log "checking the archive"
+unzip -tq "$ARCHIVE" >/dev/null 2>&1 || die "$ARCHIVE is not a readable zip archive"
+
+# Restoring from a key means reading a file out of pb_data/backups - the very
+# directory about to be moved aside. Copy it clear first, or the unpack below
+# would be reading from a path that no longer exists.
+case "$ARCHIVE" in
+	"$PB_DATA"/*)
+		mkdir -p "$APP/shared/.restore"
+		cp -a "$ARCHIVE" "$APP/shared/.restore/"
+		ARCHIVE="$APP/shared/.restore/$(basename "$ARCHIVE")"
+		CLEANUP_ARCHIVE=1
+		;;
+esac
+unzip -l "$ARCHIVE" 2>/dev/null | grep -qE '[[:space:]]data\.db$' \
+	|| die "$ARCHIVE has no data.db - it is not a PocketBase backup"
+
+# The credentials have to exist before anything moves: without them the restored
+# database cannot be reconciled, and the app would 401 on every render.
+SU_EMAIL=$(env_file_get "$ETC/env" POCKETBASE_SUPERUSER_EMAIL || true)
+SU_PASSWORD=$(env_file_get "$ETC/env" POCKETBASE_SUPERUSER_PASSWORD || true)
+[ -n "$SU_EMAIL" ] && [ -n "$SU_PASSWORD" ] \
+	|| die "$INSTANCE has no superuser credentials in its environment - deploy it first"
+
+# The archive unpacks beside the directory it replaces, and the old copy is kept
+# rather than deleted, so its space is never reclaimed. What has to be free is
+# therefore the whole unpacked archive - plus the uploads again, if they have to
+# be carried across because the archive was taken while S3 was on.
+ARCHIVE_KB=$(unzip -Zt "$ARCHIVE" | awk 'NR == 1 {print int($3 / 1024) + 1}')
+NEEDED_KB=$((ARCHIVE_KB + ARCHIVE_KB / 10))
+if ! unzip -l "$ARCHIVE" 2>/dev/null | grep -qE '[[:space:]]storage/'; then
+	NEEDED_KB=$((NEEDED_KB + $(du -sk "$PB_DATA/storage" 2>/dev/null | cut -f1 || echo 0)))
+fi
+AVAILABLE_KB=$(df -Pk "$APP" | awk 'NR == 2 {print $4}')
+if [ "$AVAILABLE_KB" -lt "$NEEDED_KB" ]; then
+	die "not enough disk space: the restore needs $((NEEDED_KB / 1024))M and $((AVAILABLE_KB / 1024))M is free"
+fi
+
+# ---------------------------------------------------------------- transaction
+
+SWAPPED=0
+RESTORED=0
+STAGE="$APP/shared/.restore-stage.$$"
+
+revert() {
+	log "restore failed - putting the previous database back"
+	if [ "$SWAPPED" = "1" ]; then
+		# Never deleted: a half-restored database is still evidence.
+		if [ -d "$PB_DATA" ]; then mv -Tf "$PB_DATA" "$APP/shared/pb_data.failed-$STAMP" || true; fi
+		# on_exit carries the original failure out; saying `die` here would only
+		# replace one non-zero code with another and re-enter this path.
+		mv -Tf "$PREVIOUS_DIR" "$PB_DATA" \
+			|| log "could not put $PREVIOUS_DIR back at $PB_DATA - this instance needs a hand"
+	fi
+	rm -rf "$STAGE"
+	systemctl start "$PB_UNIT" >/dev/null 2>&1 || true
+	systemctl start "$WEB_UNIT" >/dev/null 2>&1 || true
+}
+
+on_exit() {
+	local code=$?
+	if [ "$RESTORED" = "0" ]; then revert; fi
+	exit "$code"
+}
+trap on_exit EXIT
+
+log "stopping services"
+systemctl stop "$WEB_UNIT" >/dev/null 2>&1 || true
+systemctl stop "$PB_UNIT" >/dev/null 2>&1 || true
+
+# Unpacked next to pb_data so that the swap below is a rename on one filesystem
+# rather than a copy of everything the archive holds.
+log "unpacking $(basename "$ARCHIVE")"
+rm -rf "$STAGE"
+mkdir -p "$STAGE"
+unzip -q "$ARCHIVE" -d "$STAGE" || die "could not unpack $ARCHIVE"
+[ -f "$STAGE/data.db" ] || die "$ARCHIVE unpacked without a data.db"
+
+# The extraction ran as root. This -R is over a fresh tree of known size, which
+# is the case the recursive form is actually for.
+chown -R "$VELA_USER:$VELA_USER" "$STAGE"
+
+# An archive taken while uploads were in S3 has no storage/ at all. Copied, not
+# moved, so the directory set aside below stays a complete rollback.
+if [ ! -d "$STAGE/storage" ] && [ -d "$PB_DATA/storage" ]; then
+	log "the archive has no uploads - keeping the ones already on disk"
+	cp -a "$PB_DATA/storage" "$STAGE/storage"
+	CARRIED_STORAGE=1
+else
+	CARRIED_STORAGE=0
+fi
+
+# An archive taken from a later release than the one running carries a schema
+# this code has not seen. `migrate up` cannot help - the archive is ahead, not
+# behind - and `migrate down` is not an option either, because the migrations
+# that would reverse it live in a release that may already have been pruned. Say
+# so rather than restoring into a mismatch silently.
+if [ -d "$APP/current/migrations" ]; then
+	# `|| true` because this is advisory: an archive old enough to predate the
+	# _migrations table would otherwise fail the pipeline and abort the restore.
+	AHEAD=$(sqlite3 "$STAGE/data.db" 'select file from _migrations' 2>/dev/null \
+		| while read -r file; do
+			[ -n "$file" ] || continue
+			[ -f "$APP/current/migrations/$file" ] || printf 'x'
+		done | wc -c | tr -d ' ' || true)
+	if [ "${AHEAD:-0}" -gt 0 ] 2>/dev/null; then
+		log "warning: this backup is $AHEAD migration(s) ahead of the running release"
+		log "warning: deploy the matching code, or expect the app to see columns it does not know"
+	fi
+fi
+
+log "replacing the database"
+mv -Tf "$PB_DATA" "$PREVIOUS_DIR"
+SWAPPED=1
+mv -Tf "$STAGE" "$PB_DATA"
+
+if [ "$MIGRATE" = "1" ] && [ -d "$APP/current/migrations" ]; then
+	log "running migrations"
+	runuser -u "$VELA_USER" -- "$APP/bin/pocketbase" \
+		--dir "$PB_DATA" \
+		--migrationsDir "$APP/current/migrations" \
+		migrate up >&2 \
+		|| die "migrations failed against the restored database"
+fi
+
+# Unconditional, and after the migrations so that _superusers matches the schema
+# the running release expects. --force because the env file did not change: the
+# fingerprint cannot see that the database underneath it did.
+reconcile_superuser "$APP" "$ETC" "$SU_EMAIL" "$SU_PASSWORD" --force
+
+log "starting PocketBase on 127.0.0.1:$PB_PORT"
+systemctl start "$PB_UNIT"
+wait_for_http "http://127.0.0.1:$PB_PORT/api/health" 60 0.5 \
+	|| die "PocketBase did not become healthy - journalctl -u $PB_UNIT"
+
+# wait_for_http accepts 4xx, so the health check above passes even when the app
+# would 401 on every render. Only an actual login proves the restore is usable.
+assert_superuser_auth "$PB_PORT" "$SU_EMAIL" "$SU_PASSWORD" \
+	|| die "the restored database does not accept this instance's superuser credentials"
+
+log "starting app on 127.0.0.1:$WEB_PORT"
+systemctl start "$WEB_UNIT"
+wait_for_http "http://127.0.0.1:$WEB_PORT$HEALTH_PATH" 60 0.5 \
+	|| die "app did not become healthy at $HEALTH_PATH - journalctl -u $WEB_UNIT"
+
+RESTORED=1
+
+# ------------------------------------------------------- the backup history
+#
+# PocketBase leaves backups/ out of the archives it writes, so the restored
+# pb_data has none and every other snapshot on the box would otherwise be
+# stranded in the directory set aside above. Moved only now that the restore has
+# been proven: until this point any failure still has to be able to put the old
+# directory back exactly as it was.
+
+if [ -d "$PREVIOUS_DIR/backups" ]; then
+	log "carrying the backup history forward"
+	mkdir -p "$PB_DATA/backups"
+	find "$PREVIOUS_DIR/backups" -maxdepth 1 -type f -exec mv -t "$PB_DATA/backups" {} +
+	chown -R "$VELA_USER:$VELA_USER" "$PB_DATA/backups"
+fi
+
+# --------------------------------------------------------------------- state
+
+state_merge "$INSTANCE" "$(jq -c -n \
+	--arg at "$(date -u +%Y-%m-%dT%H:%M:%SZ)" \
+	--arg from "$(basename "$ARCHIVE")" \
+	--arg previous "$PREVIOUS_DIR" \
+	'{restoredAt: $at, restoredFrom: $from, previousDataDir: $previous}')"
+
+# ------------------------------------------------------------------- cleanup
+
+if [ "$CLEANUP_ARCHIVE" = "1" ]; then
+	rm -f "$ARCHIVE"
+	rmdir "$APP/shared/.restore" 2>/dev/null || true
+fi
+
+if [ "$KEEP_PREVIOUS" -gt 0 ] 2>/dev/null; then
+	mapfile -t old < <(ls -1d "$APP"/shared/pb_data.pre-restore-* 2>/dev/null | sort -r | tail -n +$((KEEP_PREVIOUS + 1)))
+	for dir in "${old[@]:-}"; do
+		[ -n "$dir" ] || continue
+		log "removing $(basename "$dir")"
+		rm -rf "$dir"
+	done
+fi
+
+emit_result \
+	--arg instance "$INSTANCE" --arg archive "$(basename "$ARCHIVE")" \
+	--arg previous "$PREVIOUS_DIR" --argjson migrated "$MIGRATE" \
+	--argjson storage "$CARRIED_STORAGE" \
+	'{instance: $instance, archive: $archive, previousDataDir: $previous,
+	  migrated: ($migrated == 1), storageCarriedOver: ($storage == 1)}'

package/templates/static/package.template.json

@@ -21,7 +21,7 @@
 		"@tailwindcss/forms": "^0.5.11",
 		"@tailwindcss/typography": "^0.5.19",
 		"@tailwindcss/vite": "^4.3.3",
-		"@velastack/kit": "^0.2.0",
+		"@velastack/kit": "^0.3.0",
 		"clsx": "^2.1.1",
 		"mode-watcher": "^1.1.0",
 		"prettier": "^3.9.6",