Skip to main content

Borgwarehouse

@shrug/borgwarehousev2026.11.19.2· MIT· 1d agoBEHAVIORSACCEPTED WARNINGS
01README

Swamp-native control of a BorgWarehouse backup-monitor server. HYBRID transport: HTTP REST API for all CRUD/alert/key/compact/status-cron (never edits on-host repo.json, which would race the app's lowdb mutex), and SSH + podman-exec for the one API gap: a hardened, DESTRUCTIVE pruneRepo. prune carries a full safety envelope -- caller-asserted repositoryName interlock, passphrase over ssh STDIN never in argv, --dry-run default with confirm + a mandatory keep rule + a delete-count floor, never auto break-lock, best-effort compact after. Every mutation is audited on success and failure; all secrets are vault-backed.

02Behaviors1
@shrug/borgwarehousev2026.11.19.1borgwarehouse.ts

Global Arguments

ArgumentTypeDescription
sshPort?numberSSH port
fn listRepos(_http?: any)
GET all repositories into the `repos` resource, with computed
ArgumentTypeDescription
_http?anyTest-only: inject an HttpRunner seam
fn repoStatus(slug?: string, alias?: string, _http?: any)
GET one repository (by slug=repositoryName or alias) into the
ArgumentTypeDescription
slug?stringrepositoryName (8-hex)
alias?stringHuman alias
_http?anyTest-only: inject an HttpRunner seam
fn addRepo(alias: string, sshPublicKey: string, storageSizeGb: number, alert?: number, appendOnlyMode?: boolean, comment?: string, _http?: any)
Create a repo slot (POST /repositories), IDEMPOTENT on the NORMALIZED
ArgumentTypeDescription
aliasstringHuman alias for the repo
sshPublicKeystringClient public key (globally unique in BW)
storageSizeGbnumberQuota in GB
alert?numberAlert threshold seconds (0=disabled). Default 1.5d.
appendOnlyMode?booleanForce append-only serve
comment?stringOptional comment
_http?anyTest-only: inject an HttpRunner seam
fn authorizeKey(slug?: string, alias?: string, sshPublicKey: string, appendOnly?: boolean, confirm?: boolean, _http?: any)
Set a repo's authorized client key (PATCH). First-time set (current
ArgumentTypeDescription
slug?stringrepositoryName (8-hex)
alias?stringHuman alias
sshPublicKeystringThe client public key to authorize
appendOnly?booleanForce append-only serve
confirm?booleanRequired to REKEY (replace a different existing key)
_http?anyTest-only: inject an HttpRunner seam
fn setAlert(slug?: string, alias?: string, alertSeconds: number, _http?: any)
Set a repo's alert threshold in SECONDS (PATCH). 0 disables the alert.
ArgumentTypeDescription
slug?stringrepositoryName (8-hex)
alias?stringHuman alias
alertSecondsnumberAlert threshold seconds (0=off)
_http?anyTest-only: inject an HttpRunner seam
fn compactRepo(slug?: string, alias?: string, _http?: any)
POST /repositories/{slug}/compact to reclaim segment space. A 409
ArgumentTypeDescription
slug?stringrepositoryName (8-hex)
alias?stringHuman alias
_http?anyTest-only: inject an HttpRunner seam
fn triggerStatusCron(alsoStorage?: boolean, _http?: any)
POST /cron/status (and optionally /cron/storage) with the CRONJOB_KEY
ArgumentTypeDescription
alsoStorage?booleanAlso POST /cron/storage
_http?anyTest-only: inject an HttpRunner seam
fn breakLock(slug?: string, alias?: string, confirm?: boolean, _http?: any)
Explicit stale-lock recovery: POST /repositories/{slug}/break-lock.
ArgumentTypeDescription
slug?stringrepositoryName (8-hex)
alias?stringHuman alias
confirm?booleanMust be true to break a lock
_http?anyTest-only: inject an HttpRunner seam
fn pruneRepo(slug?: string, alias?: string, keepHourly?: number, keepDaily?: number, keepWeekly?: number, keepMonthly?: number, keepYearly?: number, dryRun?: boolean, confirm?: boolean, lockWaitSeconds?: number, maxDelete?: number, allowLargeDelete?: boolean, compactAfter?: boolean, _run?: any, _http?: any)
DESTRUCTIVE: enforce retention on a repo via borg prune inside the
ArgumentTypeDescription
slug?stringrepositoryName (8-hex)
alias?stringHuman alias
keepHourly?number
keepDaily?number
keepWeekly?number
keepMonthly?number
keepYearly?number
dryRun?booleanDry-run by default; false to actually delete
confirm?booleanMust be true for a real (non-dry-run) delete
lockWaitSeconds?numberborg --lock-wait
maxDelete?numberDelete-count floor: a committing prune deleting more than this is
allowLargeDelete?booleanOverride the maxDelete floor
compactAfter?booleanPOST /compact after a committing prune
_run?anyTest-only: inject a TargetRunner (SSH) seam
_http?anyTest-only: inject an HttpRunner seam

Resources

repos(30d)— Snapshot of all repos (with computed age/stale/usage).
repoStatus(30d)— Snapshot of one repo's status.
slot(infinite)— Result of a repo-slot mutation (addRepo/authorizeKey/setAlert).
op(infinite)— Record of a compact/prune/break-lock/cron operation (output redacted).
attempt(infinite)— Audit of a mutation attempt (sanitized args + result/error). Written
03Previous Versions1
2026.11.19.1MIT
04Stats
A
100 / 100
Downloads
4
Archive size
27.2 KB
  • Has README or module doc2/2earned
  • README has a code example1/1earned
  • README is substantive1/1earned
  • Most symbols documented1/1earned
  • No slow types (deprecated)1/1earned
  • Dependencies pass trust audit2/2earned
  • Docs keep secrets in a vault1/1earned
  • Has description1/1earned
  • Platform support declared (or universal)2/2earned
  • License2/2earned
  • Verified public repository2/2earned

06Platforms
07Labels