PostgreSQL backup tool with Point-In-Time-Recovery and restore verification
TypeScript backupbackupsdatabasedatabase-backupdevopsdockergolangkubernetesmariadbmongodbmysqlpgpostgrespostgresqls3self-hostedsystem-administrationtoolsweb-ui
FEATURE (agents): Pin gopls, typescript-language-server, ripgrep and shellcheck and enable Claude Code's LSP plugins, so agents navigate code by symbols and shell scripts are linted locally and in CI
Rostislav Dugin4dba1385a3c6
diff --git a/.claude/settings.json b/.claude/settings.jsonindex dfc7645c..e4aaefd2 100644--- a/.claude/settings.json+++ b/.claude/settings.json@@ -89,5 +89,9 @@]}]+ },+ "enabledPlugins": {+ "gopls-lsp@claude-plugins-official": true,+ "typescript-lsp@claude-plugins-official": true}}diff --git a/.github/workflows/ci-release.yml b/.github/workflows/ci-release.ymlindex 12e99a04..c4623253 100644--- a/.github/workflows/ci-release.yml+++ b/.github/workflows/ci-release.yml@@ -103,6 +103,22 @@ jobs:cd frontendpnpm build+ lint-shell:+ if: github.ref != 'refs/heads/develop' && github.head_ref != 'develop'+ runs-on: namespace-profile-4vcpu-8ram-ubuntu-26-x64+ timeout-minutes: 15+ steps:+ - name: Check out code+ uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1++ - name: Install tools from mise.toml+ uses: jdx/mise-action@2d8d4cafcbd33be2ea37d2b6f5ad595363d1f1ca # v5.1.1+ with:+ install_args: "just shellcheck"++ - name: Run shellcheck+ run: just lint-shell+dockerfile-scan:if: github.ref != 'refs/heads/develop' && github.head_ref != 'develop'runs-on: namespace-profile-2vcpu-4ram-ubuntu-26-x64@@ -827,7 +843,7 @@ jobs:if: github.ref != 'refs/heads/develop' && github.head_ref != 'develop'runs-on: namespace-profile-4vcpu-8ram-ubuntu-26-x64timeout-minutes: 45- needs: [lint-backend, lint-frontend, lint-verification-agent, dockerfile-scan]+ needs: [lint-backend, lint-frontend, lint-shell, lint-verification-agent, dockerfile-scan]steps:- name: Check out codeuses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1diff --git a/.shellcheckrc b/.shellcheckrcnew file mode 100644index 00000000..dc86bc01--- /dev/null+++ b/.shellcheckrc@@ -0,0 +1,3 @@+# The scripts source their helpers by paths relative to themselves, so shellcheck follows them from there.+external-sources=true+source-path=SCRIPTDIRdiff --git a/AGENTS.md b/AGENTS.mdindex 75a37d31..a1dcdc3f 100644--- a/AGENTS.md+++ b/AGENTS.md@@ -46,6 +46,10 @@ The repository's skills live in `.agents/skills/`; `.claude/skills` is a symlink| `goose -dir backend/migrations up` (or `down`), with `.env` exported | Apply or roll back migrations on the dev database; goose reads `GOOSE_DRIVER` and `GOOSE_DBSTRING` from the environment || `swag init -d . -g cmd/main.go -o swagger`, run in `backend/` | Regenerate the API docs |+### Code search and navigation++Search text with `rg`. For definitions, references, callers, implementations and type errors, use the LSP tool: the project enables the gopls and typescript-language-server plugins in `.claude/settings.json`, and `mise.toml` pins both servers. The TypeScript server takes TypeScript from `frontend/node_modules`, so it needs `pnpm install` in `frontend/`. It answers "who calls this" and "what breaks if I rename this" more reliably than a text search, and reports compile errors right after an edit. Check shell scripts with `shellcheck`.+### Running commandsRun tests, linters and builds as ordinary foreground commands, so the user sees which command runs and that the agent is working. A backend, frontend or other long-lived process the agent started to check its work is stopped before the task ends. Long-lived processes the user wants running are started by the user.@@ -204,7 +208,7 @@ func (h *Heartbeater) IsAborted(id uuid.UUID) bool { ... }After each change run linting and formatting depending on folder you are working it.- backend and agent have `just lint` and `just format` in their folder- frontend has `pnpm lint`, `pnpm typecheck` and `pnpm format`-- `just lint` and `just format` at the root cover all three+- `just lint` and `just format` at the root cover all three; the root `just lint` also runs shellcheck on every shell script### Comments are a last resortdiff --git a/Justfile b/Justfileindex f87baae6..0b90958f 100644--- a/Justfile+++ b/Justfile@@ -15,6 +15,10 @@ lint:pnpm --dir frontend format:checkpnpm --dir frontend lintpnpm --dir frontend typecheck+ just lint-shell++lint-shell:+ git ls-files -z '*.sh' tools/lsp | xargs -0 shellcheckdoctor:.agent-hooks/run.sh doctordiff --git a/agent/verification/e2e/scripts/lib.sh b/agent/verification/e2e/scripts/lib.shindex 566f061e..7f8dff09 100644--- a/agent/verification/e2e/scripts/lib.sh+++ b/agent/verification/e2e/scripts/lib.sh@@ -6,6 +6,7 @@# (agent on the VM, sibling containers).MOCK="http://127.0.0.1:${E2E_MOCK_SERVER_PORT:-4050}"+# shellcheck disable=SC2034 # read by the test-*.sh scripts that source this fileARTIFACTS="/opt/agent/artifacts"hb_count() {diff --git a/backend/internal/features/backups/backups/controllers/physical/recovery_script.sh b/backend/internal/features/backups/backups/controllers/physical/recovery_script.shindex 1c8e9e48..28046b15 100644--- a/backend/internal/features/backups/backups/controllers/physical/recovery_script.sh+++ b/backend/internal/features/backups/backups/controllers/physical/recovery_script.sh@@ -413,6 +413,7 @@ fi# <dir>/base.tar<ext> (still compressed) plus its <dir>/backup_manifest sidecar;# pg_combinebackup reads the manifest from the extracted directory.echo "Reconstructing data directory with pg_combinebackup..."+# shellcheck disable=SC2012 # the backend names the bundle directories without spacesINCR_DIRS="$(cd "$BUNDLE_DIR" && ls -d incr-* 2>/dev/null | sort -V || true)"RECON_DIR="$BUNDLE_DIR/recon"INPUTS=""@@ -421,6 +422,7 @@ for backup in full $INCR_DIRS; dodst="$RECON_DIR/$backup"mkdir -p "$dst"+ # shellcheck disable=SC2012 # the backend names the payload files without spacesblob="$(ls "$src"/base.tar* 2>/dev/null | head -n1 || true)"if [ -z "$blob" ]; thenecho "error: backup '$backup' has no base.tar payload" >&2@@ -487,9 +489,11 @@ if [ -n "$COMBINE_IMAGE" ]; then# host-owned and the later chmod / WAL-wiring on the host can touch it) and bind# the output dir at its own absolute path so $INPUTS / $DATA_DIR resolve the same# inside and out.+ # shellcheck disable=SC2086 # INPUTS holds one directory per word, so an output path with a space breaks the restoredocker run --rm --user "$(id -u):$(id -g)" -v "$OUT_ABS:$OUT_ABS" -w "$OUT_ABS" \"$COMBINE_IMAGE" pg_combinebackup $INPUTS -o "$DATA_DIR"else+ # shellcheck disable=SC2086 # INPUTS holds one directory per word, so an output path with a space breaks the restorepg_combinebackup $INPUTS -o "$DATA_DIR"fichmod 700 "$DATA_DIR"diff --git a/databasus-recovery.sh b/databasus-recovery.shindex 90419aaf..3817ee05 100644--- a/databasus-recovery.sh+++ b/databasus-recovery.sh@@ -160,6 +160,7 @@ fi# <dir>/base.tar<ext> (still compressed) plus its <dir>/backup_manifest sidecar;# pg_combinebackup reads the manifest from the extracted directory.echo "Reconstructing data directory with pg_combinebackup..."+# shellcheck disable=SC2012 # the backend names the bundle directories without spacesINCR_DIRS="$(cd "$BUNDLE_DIR" && ls -d incr-* 2>/dev/null | sort -V || true)"RECON_DIR="$BUNDLE_DIR/recon"INPUTS=""@@ -168,6 +169,7 @@ for backup in full $INCR_DIRS; dodst="$RECON_DIR/$backup"mkdir -p "$dst"+ # shellcheck disable=SC2012 # the backend names the payload files without spacesblob="$(ls "$src"/base.tar* 2>/dev/null | head -n1 || true)"if [ -z "$blob" ]; thenecho "error: backup '$backup' has no base.tar payload" >&2@@ -192,6 +194,7 @@ for backup in full $INCR_DIRS; dodonerm -rf "$DATA_DIR"+# shellcheck disable=SC2086 # INPUTS holds one directory per word, so an output path with a space breaks the restorepg_combinebackup $INPUTS -o "$DATA_DIR"chmod 700 "$DATA_DIR"diff --git a/e2e/docker-storage/run.sh b/e2e/docker-storage/run.shindex 46e770da..c86276d8 100755--- a/e2e/docker-storage/run.sh+++ b/e2e/docker-storage/run.sh@@ -1082,6 +1082,7 @@ run_clean_shutdown() {# The loop polls without a delay, because the open step of a clean cluster lasts about 0.1 seconds.# A single-user step started by initdb works on template1, so matching the final postgres argument# skips it.+# shellcheck disable=SC2016 # the container's shell expands the scriptreadonly postgresql_freeze_script='target_kind="$1"while :; dodiff --git a/mise.toml b/mise.tomlindex 7a25938e..d969ed30 100644--- a/mise.toml+++ b/mise.toml@@ -12,3 +12,11 @@ golangci-lint = "2.11.3""npm:chrome-devtools-mcp" = "1.11.0"python = "3.14.7""npm:@fission-ai/openspec" = "1.11.0"+"go:golang.org/x/tools/gopls" = "v0.24.0"+"npm:typescript-language-server" = "6.0.2"+ripgrep = "15.2.0"+shellcheck = "0.11.0"++[env]+# tools/lsp/typescript-language-server explains why it shadows the mise shim.+_.path = ["{{config_root}}/tools/lsp"]diff --git a/scripts/dev.sh b/scripts/dev.shindex 435cd150..77b9603e 100755--- a/scripts/dev.sh+++ b/scripts/dev.sh@@ -31,11 +31,13 @@ stop_stale_backend_watchers() {# fails to bind only logs the error, so requests silently hit the old binary. Its watcher is stopped# first by stop_stale_backend_watchers, because air would otherwise start the backend again.free_backend_port() {- local port_hex inode pid+ local port_hex inode process_dir pidport_hex=$(printf ':%04X' "$backend_port")inode=$(awk -v p="$port_hex" '$4 == "0A" && $2 ~ p"$" {print $10}' /proc/net/tcp /proc/net/tcp6 | head -1)[[ -n "$inode" ]] || return 0- for pid in $(ls /proc | grep -E '^[0-9]+$'); do+ for process_dir in /proc/[0-9]*; do+ pid=${process_dir#/proc/}+ # shellcheck disable=SC2010 # the match is on the socket link targets, not on file namesif ls -l "/proc/$pid/fd" 2>/dev/null | grep -q "socket:\[$inode\]"; thenecho "freeing port $backend_port: killing stale backend pid $pid"kill -9 "$pid" 2>/dev/null || truediff --git a/scripts/test.sh b/scripts/test.shindex 714056e7..5a535f61 100755--- a/scripts/test.sh+++ b/scripts/test.sh@@ -12,6 +12,7 @@ cleanup() {local idsids=$(docker ps -aq --filter "label=org.testcontainers")if [[ -n "$ids" ]]; then+ # shellcheck disable=SC2086 # one container ID per worddocker rm -f $ids >/dev/nullfi}diff --git a/tools/lsp/typescript-language-server b/tools/lsp/typescript-language-servernew file mode 100755index 00000000..b99c5873--- /dev/null+++ b/tools/lsp/typescript-language-server@@ -0,0 +1,10 @@+#!/usr/bin/env bash+# Claude Code's typescript-lsp plugin starts this server at the repository root, where no typescript+# package is installed, so the server falls back to resolving it through NODE_PATH. The mise shim+# replaces NODE_PATH with its own, so this wrapper, which mise.toml puts ahead of the shim on PATH,+# runs the pinned server directly and gives it the frontend's TypeScript.+set -euo pipefail++root="$(cd "${BASH_SOURCE[0]%/*}/../.." && pwd)"+server_dir="$(mise where npm:typescript-language-server)"+NODE_PATH="$root/frontend/node_modules" exec node "$server_dir/node_modules/typescript-language-server/lib/cli.mjs" "$@"