Borgwarehouse
@shrug/borgwarehousev2026.11.19.2
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.
02Behaviors
@shrug/borgwarehousev2026.11.19.1borgwarehouse.ts
Global Arguments
| Argument | Type | Description |
|---|---|---|
| sshPort? | number | SSH port |
fn listRepos(_http?: any)
GET all repositories into the `repos` resource, with computed
| Argument | Type | Description |
|---|---|---|
| _http? | any | Test-only: inject an HttpRunner seam |
fn repoStatus(slug?: string, alias?: string, _http?: any)
GET one repository (by slug=repositoryName or alias) into the
| Argument | Type | Description |
|---|---|---|
| slug? | string | repositoryName (8-hex) |
| alias? | string | Human alias |
| _http? | any | Test-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
| Argument | Type | Description |
|---|---|---|
| alias | string | Human alias for the repo |
| sshPublicKey | string | Client public key (globally unique in BW) |
| storageSizeGb | number | Quota in GB |
| alert? | number | Alert threshold seconds (0=disabled). Default 1.5d. |
| appendOnlyMode? | boolean | Force append-only serve |
| comment? | string | Optional comment |
| _http? | any | Test-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
| Argument | Type | Description |
|---|---|---|
| slug? | string | repositoryName (8-hex) |
| alias? | string | Human alias |
| sshPublicKey | string | The client public key to authorize |
| appendOnly? | boolean | Force append-only serve |
| confirm? | boolean | Required to REKEY (replace a different existing key) |
| _http? | any | Test-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.
| Argument | Type | Description |
|---|---|---|
| slug? | string | repositoryName (8-hex) |
| alias? | string | Human alias |
| alertSeconds | number | Alert threshold seconds (0=off) |
| _http? | any | Test-only: inject an HttpRunner seam |
fn compactRepo(slug?: string, alias?: string, _http?: any)
POST /repositories/{slug}/compact to reclaim segment space. A 409
| Argument | Type | Description |
|---|---|---|
| slug? | string | repositoryName (8-hex) |
| alias? | string | Human alias |
| _http? | any | Test-only: inject an HttpRunner seam |
fn triggerStatusCron(alsoStorage?: boolean, _http?: any)
POST /cron/status (and optionally /cron/storage) with the CRONJOB_KEY
| Argument | Type | Description |
|---|---|---|
| alsoStorage? | boolean | Also POST /cron/storage |
| _http? | any | Test-only: inject an HttpRunner seam |
fn breakLock(slug?: string, alias?: string, confirm?: boolean, _http?: any)
Explicit stale-lock recovery: POST /repositories/{slug}/break-lock.
| Argument | Type | Description |
|---|---|---|
| slug? | string | repositoryName (8-hex) |
| alias? | string | Human alias |
| confirm? | boolean | Must be true to break a lock |
| _http? | any | Test-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
| Argument | Type | Description |
|---|---|---|
| slug? | string | repositoryName (8-hex) |
| alias? | string | Human alias |
| keepHourly? | number | |
| keepDaily? | number | |
| keepWeekly? | number | |
| keepMonthly? | number | |
| keepYearly? | number | |
| dryRun? | boolean | Dry-run by default; false to actually delete |
| confirm? | boolean | Must be true for a real (non-dry-run) delete |
| lockWaitSeconds? | number | borg --lock-wait |
| maxDelete? | number | Delete-count floor: a committing prune deleting more than this is |
| allowLargeDelete? | boolean | Override the maxDelete floor |
| compactAfter? | boolean | POST /compact after a committing prune |
| _run? | any | Test-only: inject a TargetRunner (SSH) seam |
| _http? | any | Test-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 Versions
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
deno-command1 accepted
Spawns a subprocess with Deno.Command().
- models/borgwarehouse.ts:270 — no reason given
06Platforms
07Labels