Absorb functionality

docs/guide/shots.py

@@ -315,6 +315,35 @@ def main():
     t.cmd("ls Scans")
     shoot("migrate", t)
 
+    # absorb: a tar archive piped in, here pulled from a gzipped tarball
+    box.write("Projects/website/index.html", "<h1>hello</h1>\n")
+    box.write("Projects/website/css/site.css", "body{}\n")
+    box.write("Projects/website/img/logo.png", os.urandom(24_311))
+    t = Term(box)
+    t.cmd("tar -czf website.tar.gz -C Projects website")
+    t.cmd("vault absorb backups < website.tar.gz", P)
+    t.cmd("tar -c recipes | vault absorb old", P)
+    t.cmd("vault list backups", P)
+    shoot("absorb", t)
+
+    # mirror: a tiny local site, served on localhost
+    site = os.path.join(box.root, "site")
+    for rel, body in {"index.html": '<a href="/about.html">About</a> <link href="/style.css">',
+                      "about.html": '<a href="/">Home</a> <img src="/img/me.png">',
+                      "style.css": "body{background:url(/img/bg.png)}",
+                      "img/me.png": "png", "img/bg.png": "png"}.items():
+        os.makedirs(os.path.dirname(os.path.join(site, rel)), exist_ok=True)
+        with open(os.path.join(site, rel), "w") as f:
+            f.write(body)
+    srv = subprocess.Popen([sys.executable, "-m", "http.server", "8000", "--bind", "127.0.0.1"],
+                           cwd=site, stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL)
+    time.sleep(1)
+    t = Term(box)
+    t.cmd("vault mirror http://localhost:8000/ sites", P)
+    t.cmd("vault get sites/localhost:8000/about.html && cat about.html", P)
+    shoot("mirror", t)
+    srv.terminate()
+
     # errors
     t = Term(box)
     t.cmd("vault list", "hunter2", highlight=("incorrect",))

docs/guide/vault-guide.tex

@@ -567,6 +567,22 @@ the whole site, one request at a time, into a folder named after its host.
 Links inside pages and stylesheets are rewritten to relative paths, so the
 copy still browses once you get it out. Only the same host is followed.
 
+\subsection{From a tar archive: \texttt{absorb}}
+\cmd{absorb} reads a tar archive, gzipped or not, from standard input and
+stores every plain file in it, optionally under a folder:
+
+\begin{verbatim}
+tar -cz photos | vault absorb backup
+ssh server 'tar -c /etc' | vault absorb server1
+vault absorb old < archive.tar.gz
+\end{verbatim}
+
+Each file is encrypted straight from the stream, so nothing is unpacked to
+disk first. Directories need no entry of their own; links, devices and any
+name that tries to climb out with \file{..} are skipped with a note. If the
+archive stops halfway through a file, that file isn't stored and vault
+stops; everything before it is already safely in.
+
 \subsection{Moving in: \texttt{migrate}}
 \cmd{migrate} works exactly like \cmd{add}, but deletes each original once
 it's safely stored, then tidies away any folders left empty. It won't take a

docs/vault-absorb.1

@@ -0,0 +1,73 @@
+.TH VAULT-ABSORB 1 "October 2026" "vault" "User Commands"
+.SH NAME
+vault-absorb \- add the files in a tar archive to an encrypted vault
+.SH SYNOPSIS
+.B vault absorb
+.RB [ \-\-key
+.IR PATH ]
+.RB [ \-\-vault
+.IR DIR ]
+.RI [ FOLDER ]
+.B <
+.I ARCHIVE
+.SH DESCRIPTION
+.B vault absorb
+reads a tar archive from standard input and stores every regular file in
+it, beneath
+.I FOLDER
+if one is given, keeping the paths, permissions and modification times
+recorded in the archive. A gzip-compressed archive is detected and
+unpacked automatically.
+.PP
+Each file is encrypted straight from the stream; nothing is unpacked to
+disk. Anything already stored under the same name is replaced.
+.PP
+Directory entries are not stored (directories exist implicitly). Symbolic
+and hard links, devices and other special entries are reported on standard
+error and skipped, as is any entry whose name would escape
+.I FOLDER
+through
+.BR .. .
+A leading
+.B ./
+or
+.B /
+is dropped.
+.PP
+The passphrase prompt reads from the terminal, not standard input, so
+it still works with an archive piped in. The vault is locked exclusively
+for the whole run.
+.SH OPTIONS
+.TP
+.BI \-\-key " PATH"
+Key file. Default: $VAULT_KEY, else ~/.vault/key.
+.TP
+.BI \-\-vault " DIR"
+Vault directory. Default: $VAULT_DIR, else ~/.vault/store.
+.SH ENVIRONMENT
+.TP
+.B VAULT_PASSPHRASE
+Passphrase, instead of prompting on the terminal.
+.SH EXIT STATUS
+0 if at least one file was stored and the archive was read to the end.
+1 if the archive is malformed or ends early, holds no regular files, or
+anything fails; files stored before the failure stay in the vault.
+.SH EXAMPLES
+Store a directory under
+.BR backup/photos/ :
+.PP
+.RS
+tar \-cz photos | vault absorb backup
+.RE
+.PP
+Pull a remote directory straight into the vault:
+.PP
+.RS
+ssh server 'tar \-C /etc \-c .' | vault absorb server1/etc
+.RE
+.SH SEE ALSO
+.BR vault (1),
+.BR vault\-add (1),
+.BR tar (1)
+.SH AUTHOR
+Andy Dixon <vault@dixon.cx>, https://www.dixon.cx

docs/vault-add.1

@@ -41,6 +41,7 @@ vault add https://example.com/paper.pdf papers
 .SH SEE ALSO
 .BR vault (1),
 .BR vault\-migrate (1),
-.BR vault\-mirror (1)
+.BR vault\-mirror (1),
+.BR vault\-absorb (1)
 .SH AUTHOR
 Andy Dixon <vault@dixon.cx>, https://www.dixon.cx

docs/vault.1

@@ -33,6 +33,9 @@ Like add, then delete each original.
 .BR vault\-mirror (1)
 Crawl a website into the vault.
 .TP
+.BR vault\-absorb (1)
+Add every file in a tar archive read from standard input.
+.TP
 .BR vault\-list (1)
 List stored files (alias:
 .BR ls ).