Skip to content

PostgreSQL backup tool with Point-In-Time-Recovery and restore verification

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.json
index 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.yml
index 12e99a04..c4623253 100644
--- a/.github/workflows/ci-release.yml
+++ b/.github/workflows/ci-release.yml
@@ -103,6 +103,22 @@ jobs:
cd frontend
pnpm 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-x64
timeout-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 code
uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1
diff --git a/.shellcheckrc b/.shellcheckrc
new file mode 100644
index 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=SCRIPTDIR
diff --git a/AGENTS.md b/AGENTS.md
index 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 commands
Run 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 resort
diff --git a/Justfile b/Justfile
index f87baae6..0b90958f 100644
--- a/Justfile
+++ b/Justfile
@@ -15,6 +15,10 @@ lint:
pnpm --dir frontend format:check
pnpm --dir frontend lint
pnpm --dir frontend typecheck
+ just lint-shell
+
+lint-shell:
+ git ls-files -z '*.sh' tools/lsp | xargs -0 shellcheck
doctor:
.agent-hooks/run.sh doctor
diff --git a/agent/verification/e2e/scripts/lib.sh b/agent/verification/e2e/scripts/lib.sh
index 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 file
ARTIFACTS="/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.sh
index 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 spaces
INCR_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; do
dst="$RECON_DIR/$backup"
mkdir -p "$dst"
+ # shellcheck disable=SC2012 # the backend names the payload files without spaces
blob="$(ls "$src"/base.tar* 2>/dev/null | head -n1 || true)"
if [ -z "$blob" ]; then
echo "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 restore
docker 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 restore
pg_combinebackup $INPUTS -o "$DATA_DIR"
fi
chmod 700 "$DATA_DIR"
diff --git a/databasus-recovery.sh b/databasus-recovery.sh
index 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 spaces
INCR_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; do
dst="$RECON_DIR/$backup"
mkdir -p "$dst"
+ # shellcheck disable=SC2012 # the backend names the payload files without spaces
blob="$(ls "$src"/base.tar* 2>/dev/null | head -n1 || true)"
if [ -z "$blob" ]; then
echo "error: backup '$backup' has no base.tar payload" >&2
@@ -192,6 +194,7 @@ for backup in full $INCR_DIRS; do
done
rm -rf "$DATA_DIR"
+# shellcheck disable=SC2086 # INPUTS holds one directory per word, so an output path with a space breaks the restore
pg_combinebackup $INPUTS -o "$DATA_DIR"
chmod 700 "$DATA_DIR"
diff --git a/e2e/docker-storage/run.sh b/e2e/docker-storage/run.sh
index 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 script
readonly postgresql_freeze_script='
target_kind="$1"
while :; do
diff --git a/mise.toml b/mise.toml
index 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.sh
index 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 pid
port_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 names
if ls -l "/proc/$pid/fd" 2>/dev/null | grep -q "socket:\[$inode\]"; then
echo "freeing port $backend_port: killing stale backend pid $pid"
kill -9 "$pid" 2>/dev/null || true
diff --git a/scripts/test.sh b/scripts/test.sh
index 714056e7..5a535f61 100755
--- a/scripts/test.sh
+++ b/scripts/test.sh
@@ -12,6 +12,7 @@ cleanup() {
local ids
ids=$(docker ps -aq --filter "label=org.testcontainers")
if [[ -n "$ids" ]]; then
+ # shellcheck disable=SC2086 # one container ID per word
docker rm -f $ids >/dev/null
fi
}
diff --git a/tools/lsp/typescript-language-server b/tools/lsp/typescript-language-server
new file mode 100755
index 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" "$@"