openryoko 2026.10.8 → 2026.10.13

package/dist/src/backup/tar.js

@@ -0,0 +1,274 @@
+/**
+ * The subset of tar a home archive needs, read and written in-process.
+ *
+ * No external `tar` is spawned: the gateway runs in containers with a read-only
+ * root and whatever userland the image happens to ship, and a restore has to
+ * inspect every entry before a single byte is written - which a child process
+ * extracting on its own does not allow. The format stays plain ustar with pax
+ * records for long or non-ASCII names, so any system tar can still open an
+ * archive by hand.
+ *
+ * Only files, directories and symlinks exist here. Hard links, devices and the
+ * GNU extensions are refused on read rather than interpreted.
+ */
+export const TAR_BLOCK_BYTES = 512;
+/** Two zero blocks close an archive. */
+export const TAR_TRAILER = Buffer.alloc(TAR_BLOCK_BYTES * 2);
+/**
+ * How much may follow the end-of-archive marker. Tar writers round an archive
+ * up to their record size with zeroes - ten kilobytes by default - and that is
+ * all that belongs there.
+ */
+export const MAX_TRAILING_PADDING_BYTES = 64 * 1024;
+/** Largest value an 11-digit octal field holds (8 GiB - 1). Past it the size rides in a pax record. */
+const USTAR_MAX_SIZE = 0o77777777777;
+const USTAR_NAME_BYTES = 100;
+/**
+ * A pax header only ever carries a path, a link target and a size, and it has
+ * to be held whole before it can be used. Sixteen kilobytes is several times
+ * the longest path any filesystem allows.
+ */
+const PAX_MAX_BYTES = 16 * 1024;
+const PLAIN_ASCII = /^[\x20-\x7e]*$/;
+const PAX_TYPEFLAG = "x";
+const TYPEFLAGS = { file: "0", directory: "5", symlink: "2" };
+const ENTRY_TYPES = { "0": "file", "\0": "file", "5": "directory", "2": "symlink" };
+function writeField(block, text, offset, length) {
+    const bytes = Buffer.from(text, "utf8");
+    if (bytes.length > length)
+        throw new Error(`tar header field overflow (${bytes.length} > ${length} bytes)`);
+    bytes.copy(block, offset);
+}
+function octal(value, width) {
+    return `${Math.max(0, Math.floor(value)).toString(8).padStart(width - 1, "0")}\0`;
+}
+/** One raw 512-byte ustar header. Exposed so tests can build entries the writer never would. */
+export function encodeTarHeaderBlock(fields) {
+    const block = Buffer.alloc(TAR_BLOCK_BYTES);
+    writeField(block, fields.name, 0, USTAR_NAME_BYTES);
+    writeField(block, octal(fields.mode & 0o7777, 8), 100, 8);
+    writeField(block, octal(0, 8), 108, 8);
+    writeField(block, octal(0, 8), 116, 8);
+    writeField(block, octal(fields.size, 12), 124, 12);
+    writeField(block, octal(Math.min(fields.mtimeSeconds, USTAR_MAX_SIZE), 12), 136, 12);
+    block.fill(0x20, 148, 156);
+    writeField(block, fields.typeflag, 156, 1);
+    if (fields.linkname)
+        writeField(block, fields.linkname, 157, USTAR_NAME_BYTES);
+    writeField(block, "ustar\0", 257, 6);
+    writeField(block, "00", 263, 2);
+    let sum = 0;
+    for (const byte of block)
+        sum += byte;
+    writeField(block, `${sum.toString(8).padStart(6, "0")}\0 `, 148, 8);
+    return block;
+}
+/** Zero bytes that bring `size` bytes of data up to the next block boundary. */
+export function tarPadding(size) {
+    return Buffer.alloc((TAR_BLOCK_BYTES - (size % TAR_BLOCK_BYTES)) % TAR_BLOCK_BYTES);
+}
+function fitsUstar(text) {
+    return PLAIN_ASCII.test(text) && text.length <= USTAR_NAME_BYTES;
+}
+/** What a reader without pax support would see; ours always prefers the record. */
+function ustarFallback(text) {
+    return text.replace(/[^\x20-\x7e]/g, "_").slice(0, USTAR_NAME_BYTES);
+}
+/** `<length> <key>=<value>\n`, where the length counts its own digits. */
+function paxRecord(key, value) {
+    const body = Buffer.from(` ${key}=${value}\n`, "utf8");
+    let length = body.length;
+    for (;;) {
+        const next = body.length + String(length).length;
+        if (next === length)
+            break;
+        length = next;
+    }
+    return Buffer.concat([Buffer.from(String(length), "latin1"), body]);
+}
+/** The header block(s) for one entry: a pax header first when ustar cannot hold it. */
+export function encodeTarEntry(entry) {
+    const name = entry.type === "directory" ? `${entry.path}/` : entry.path;
+    const size = entry.type === "file" ? entry.size : 0;
+    const linkTarget = entry.type === "symlink" ? entry.linkTarget ?? "" : undefined;
+    const records = [];
+    if (!fitsUstar(name))
+        records.push(paxRecord("path", name));
+    if (linkTarget !== undefined && !fitsUstar(linkTarget))
+        records.push(paxRecord("linkpath", linkTarget));
+    if (size > USTAR_MAX_SIZE)
+        records.push(paxRecord("size", String(size)));
+    const header = encodeTarHeaderBlock({
+        name: ustarFallback(name),
+        mode: entry.mode,
+        size: size > USTAR_MAX_SIZE ? 0 : size,
+        mtimeSeconds: entry.mtimeSeconds,
+        typeflag: TYPEFLAGS[entry.type],
+        ...(linkTarget !== undefined ? { linkname: ustarFallback(linkTarget) } : {}),
+    });
+    if (records.length === 0)
+        return header;
+    const body = Buffer.concat(records);
+    const pax = encodeTarHeaderBlock({
+        name: "PaxHeader", mode: 0o644, size: body.length, mtimeSeconds: entry.mtimeSeconds, typeflag: PAX_TYPEFLAG,
+    });
+    return Buffer.concat([pax, body, tarPadding(body.length), header]);
+}
+function parseOctal(block, offset, length, label) {
+    // The high bit marks GNU's base-256 encoding; this codec writes pax records instead.
+    if (block[offset] & 0x80)
+        throw new Error(`unsupported ${label} encoding in tar header`);
+    const text = block.toString("latin1", offset, offset + length).replace(/\0[\s\S]*$/, "").trim();
+    if (text === "")
+        return 0;
+    if (!/^[0-7]+$/.test(text))
+        throw new Error(`corrupt ${label} in tar header`);
+    return parseInt(text, 8);
+}
+function readText(block, offset, length) {
+    const end = block.indexOf(0, offset);
+    return block.toString("utf8", offset, end === -1 || end > offset + length ? offset + length : end);
+}
+function checksumMatches(block) {
+    const stored = parseOctal(block, 148, 8, "checksum");
+    let sum = 0;
+    for (let index = 0; index < TAR_BLOCK_BYTES; index += 1)
+        sum += index >= 148 && index < 156 ? 0x20 : block[index];
+    return sum === stored;
+}
+function isZeroFilled(bytes) {
+    for (const byte of bytes)
+        if (byte !== 0)
+            return false;
+    return true;
+}
+function parsePaxRecords(body) {
+    const records = {};
+    let offset = 0;
+    while (offset < body.length) {
+        const space = body.indexOf(0x20, offset);
+        const length = space === -1 ? Number.NaN : Number(body.toString("latin1", offset, space));
+        if (!Number.isInteger(length) || length <= space - offset + 1 || offset + length > body.length) {
+            throw new Error("corrupt pax header in tar archive");
+        }
+        const record = body.toString("utf8", space + 1, offset + length - 1);
+        const separator = record.indexOf("=");
+        if (separator === -1)
+            throw new Error("corrupt pax header in tar archive");
+        records[record.slice(0, separator)] = record.slice(separator + 1);
+        offset += length;
+    }
+    return records;
+}
+/** Pulls exact byte counts out of a stream that hands over chunks of any size. */
+class ByteReader {
+    source;
+    current = Buffer.alloc(0);
+    offset = 0;
+    constructor(source) {
+        this.source = source;
+    }
+    async refill() {
+        const next = await this.source.next();
+        if (next.done)
+            return false;
+        const chunk = next.value;
+        this.current = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk.buffer, chunk.byteOffset, chunk.byteLength);
+        this.offset = 0;
+        return true;
+    }
+    /** Hands `bytes` bytes to `write` in whatever slices the stream delivers them. */
+    async forward(bytes, write) {
+        let needed = bytes;
+        while (needed > 0) {
+            if (this.offset >= this.current.length && !(await this.refill()))
+                throw new Error("truncated tar archive");
+            const take = Math.min(needed, this.current.length - this.offset);
+            if (take > 0)
+                await write(this.current.subarray(this.offset, this.offset + take));
+            this.offset += take;
+            needed -= take;
+        }
+    }
+    async read(bytes) {
+        const parts = [];
+        await this.forward(bytes, (chunk) => { parts.push(chunk); });
+        return parts.length === 1 ? parts[0] : Buffer.concat(parts, bytes);
+    }
+    /** Everything left in the stream, which the caller must still look at. */
+    async *rest() {
+        if (this.offset < this.current.length)
+            yield this.current.subarray(this.offset);
+        while (await this.refill())
+            yield this.current;
+    }
+}
+function entryFromHeader(block, pax) {
+    const typeflag = String.fromCharCode(block[156]);
+    const prefix = readText(block, 345, 155);
+    const name = readText(block, 0, USTAR_NAME_BYTES);
+    const rawPath = pax.path ?? (prefix ? `${prefix}/${name}` : name);
+    const type = ENTRY_TYPES[typeflag];
+    if (!type)
+        throw new Error(`unsupported tar entry type "${typeflag}" for ${rawPath}`);
+    const size = pax.size !== undefined ? Number(pax.size) : parseOctal(block, 124, 12, "size");
+    if (!Number.isSafeInteger(size) || size < 0)
+        throw new Error(`corrupt size in tar header for ${rawPath}`);
+    if (type !== "file" && size !== 0)
+        throw new Error(`a ${type} entry must not carry data: ${rawPath}`);
+    return {
+        path: type === "directory" ? rawPath.replace(/\/+$/, "") : rawPath,
+        type,
+        mode: parseOctal(block, 100, 8, "mode") & 0o7777,
+        size,
+        mtimeSeconds: parseOctal(block, 136, 12, "mtime"),
+        ...(type === "symlink" ? { linkTarget: pax.linkpath ?? readText(block, 157, USTAR_NAME_BYTES) } : {}),
+    };
+}
+async function readPaxRecords(reader, block) {
+    const size = parseOctal(block, 124, 12, "size");
+    if (size > PAX_MAX_BYTES)
+        throw new Error("pax header in tar archive is implausibly large");
+    const body = await reader.read(size);
+    await reader.read(tarPadding(size).length);
+    return parsePaxRecords(body);
+}
+/**
+ * Walks a tar stream entry by entry.
+ *
+ * `onEntry` decides what happens to each entry's data: return a sink to receive
+ * it, or nothing to have it skipped. A sound archive is read to its end - the
+ * caller's decompressor only verifies its checksum once it is drained - and
+ * anything other than padding after the end-of-archive marker is refused. So
+ * is padding that goes on: zeroes compress to nothing, and a stream of them
+ * after the marker would otherwise be read for as long as it lasted.
+ */
+export async function readTar(source, onEntry) {
+    const reader = new ByteReader(source[Symbol.asyncIterator]());
+    let pax = {};
+    for (;;) {
+        const block = await reader.read(TAR_BLOCK_BYTES);
+        if (isZeroFilled(block))
+            break;
+        if (!block.toString("latin1", 257, 262).startsWith("ustar") || !checksumMatches(block)) {
+            throw new Error("corrupt tar header (checksum mismatch)");
+        }
+        if (String.fromCharCode(block[156]) === PAX_TYPEFLAG) {
+            pax = await readPaxRecords(reader, block);
+            continue;
+        }
+        const entry = entryFromHeader(block, pax);
+        pax = {};
+        const sink = await onEntry(entry);
+        await reader.forward(entry.size, (chunk) => sink?.write(chunk));
+        await reader.read(tarPadding(entry.size).length);
+        await sink?.end();
+    }
+    let trailing = 0;
+    for await (const chunk of reader.rest()) {
+        trailing += chunk.length;
+        if (trailing > MAX_TRAILING_PADDING_BYTES || !isZeroFilled(chunk))
+            throw new Error("unexpected data after the end of the archive");
+    }
+}
+//# sourceMappingURL=tar.js.map

package/dist/src/backup/tar.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tar.js","sourceRoot":"","sources":["../../../src/backup/tar.ts"],"names":[],"mappings":"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"}

package/dist/src/backup/targets.d.ts

@@ -0,0 +1,85 @@
+export type ArchiveEntryType = "file" | "directory" | "symlink";
+/**
+ * What a home archive holds, and the names `ryoko backup restore --only` takes.
+ *
+ * This is the one list. The archive writer walks it, restore maps every entry
+ * back to a kind through it, and nothing outside it is ever written into a home:
+ * an archive entry that falls under none of these is ignored on restore,
+ * whoever put it there.
+ *
+ * A path named here wins over the pattern, which is how MEMORY.md stays with
+ * the memory while every other document in the home is persona. `.env` rides
+ * with the config: some operators keep their scripts' keys there, and the
+ * archive already carries the tokens in config.yaml.
+ *
+ * Deliberately absent: `logs/`, `tmp/`, `files/` (uploads), `backups/`,
+ * `.migration-backups/`, `sessions/` and the SQLite files (the database backup
+ * covers those with SQLite's own online copy), `cron/commands/` (run locks and
+ * captured output), and the gateway's runtime and auth state - `credentials/`,
+ * `connectors/`, `.whatsapp-auth`, `gateway-auth.json`, `auth-devices.json`.
+ * Auth state is not something anyone edits; after a total loss it is
+ * re-established, not restored.
+ */
+export declare const HOME_ARCHIVE_TARGETS: readonly [{
+    readonly kind: "config";
+    readonly paths: readonly ["config.yaml", ".env"];
+}, {
+    readonly kind: "cron";
+    readonly paths: readonly ["cron/jobs.json"];
+}, {
+    readonly kind: "cron-history";
+    readonly paths: readonly ["cron/runs"];
+}, {
+    readonly kind: "persona";
+    readonly paths: readonly [];
+    readonly topLevelFiles: RegExp;
+}, {
+    readonly kind: "memory";
+    readonly paths: readonly ["MEMORY.md", "memory"];
+}, {
+    readonly kind: "org";
+    readonly paths: readonly ["org"];
+}, {
+    readonly kind: "skills";
+    readonly paths: readonly ["skills", "skills.json"];
+}, {
+    readonly kind: "docs";
+    readonly paths: readonly ["docs"];
+}, {
+    readonly kind: "knowledge";
+    readonly paths: readonly ["knowledge"];
+}, {
+    readonly kind: "workflows";
+    readonly paths: readonly ["workflows"];
+}];
+export type BackupKind = (typeof HOME_ARCHIVE_TARGETS)[number]["kind"];
+/** The name patterns the walker looks for directly in the home, with the kind each belongs to. */
+export declare const TOP_LEVEL_FILE_TARGETS: readonly {
+    kind: BackupKind;
+    pattern: RegExp;
+}[];
+export declare const BACKUP_KINDS: readonly BackupKind[];
+/**
+ * Reproducible caches and nested checkouts, skipped at any depth. A skill that
+ * vendors its own clone or virtualenv can outweigh the rest of the home, and
+ * none of it is content the operator would lose.
+ */
+export declare const EXCLUDED_DIRECTORY_NAMES: readonly string[];
+/** Where the manifest rides inside the archive. Not a home path, so it can never collide with one. */
+export declare const MANIFEST_ENTRY_PATH = ".backup-manifest.json";
+/** True for a home-relative path the walker must leave out of the archive. */
+export declare function isExcludedPath(relativePath: string, isDirectory: boolean): boolean;
+/**
+ * The kind an archive entry belongs to, or null for one no target covers.
+ * `type` matters only for the name patterns: a directory that happens to be
+ * called `drafts.md` is not a document.
+ */
+export declare function kindOfPath(entryPath: string, type?: ArchiveEntryType): BackupKind | null;
+/**
+ * Why an archive entry path must not be trusted, or null when it is the plain
+ * relative form the writer produces. Anything else - absolute, climbing out with
+ * `..`, or merely not canonical - is refused rather than normalized: a path that
+ * needs interpreting is a path that can be interpreted two ways.
+ */
+export declare function unsafePathReason(entryPath: string): string | null;
+//# sourceMappingURL=targets.d.ts.map

package/dist/src/backup/targets.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"targets.d.ts","sourceRoot":"","sources":["../../../src/backup/targets.ts"],"names":[],"mappings":"AAEA,MAAM,MAAM,gBAAgB,GAAG,MAAM,GAAG,WAAW,GAAG,SAAS,CAAC;AAmBhE;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,eAAO,MAAM,oBAAoB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAWY,CAAC;AAE9C,MAAM,MAAM,UAAU,GAAG,CAAC,OAAO,oBAAoB,CAAC,CAAC,MAAM,CAAC,CAAC,MAAM,CAAC,CAAC;AAEvE,kGAAkG;AAClG,eAAO,MAAM,sBAAsB,EAAE,SAAS;IAAE,IAAI,EAAE,UAAU,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,EAC8B,CAAC;AAElH,eAAO,MAAM,YAAY,EAAE,SAAS,UAAU,EAAsD,CAAC;AAErG;;;;GAIG;AACH,eAAO,MAAM,wBAAwB,EAAE,SAAS,MAAM,EAAqD,CAAC;AAK5G,sGAAsG;AACtG,eAAO,MAAM,mBAAmB,0BAA0B,CAAC;AAE3D,8EAA8E;AAC9E,wBAAgB,cAAc,CAAC,YAAY,EAAE,MAAM,EAAE,WAAW,EAAE,OAAO,GAAG,OAAO,CAGlF;AAED;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,GAAE,gBAAyB,GAAG,UAAU,GAAG,IAAI,CAQhG;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAYjE"}

package/dist/src/backup/targets.js

@@ -0,0 +1,104 @@
+import path from "node:path";
+/**
+ * A Markdown file directly in the home. Matched by what it is rather than by a
+ * list of names: the instruction and persona files the template ships are
+ * here, and so are BOOTSTRAP.md and whatever documents an operator keeps
+ * beside them, which no list could have named in advance. A retired copy such
+ * as `AGENTS.md.bak-20261001` does not end in `.md` and stays out.
+ */
+const DOCUMENT_IN_HOME = /^[^/]+\.md$/;
+/**
+ * What a home archive holds, and the names `ryoko backup restore --only` takes.
+ *
+ * This is the one list. The archive writer walks it, restore maps every entry
+ * back to a kind through it, and nothing outside it is ever written into a home:
+ * an archive entry that falls under none of these is ignored on restore,
+ * whoever put it there.
+ *
+ * A path named here wins over the pattern, which is how MEMORY.md stays with
+ * the memory while every other document in the home is persona. `.env` rides
+ * with the config: some operators keep their scripts' keys there, and the
+ * archive already carries the tokens in config.yaml.
+ *
+ * Deliberately absent: `logs/`, `tmp/`, `files/` (uploads), `backups/`,
+ * `.migration-backups/`, `sessions/` and the SQLite files (the database backup
+ * covers those with SQLite's own online copy), `cron/commands/` (run locks and
+ * captured output), and the gateway's runtime and auth state - `credentials/`,
+ * `connectors/`, `.whatsapp-auth`, `gateway-auth.json`, `auth-devices.json`.
+ * Auth state is not something anyone edits; after a total loss it is
+ * re-established, not restored.
+ */
+export const HOME_ARCHIVE_TARGETS = [
+    { kind: "config", paths: ["config.yaml", ".env"] },
+    { kind: "cron", paths: ["cron/jobs.json"] },
+    { kind: "cron-history", paths: ["cron/runs"] },
+    { kind: "persona", paths: [], topLevelFiles: DOCUMENT_IN_HOME },
+    { kind: "memory", paths: ["MEMORY.md", "memory"] },
+    { kind: "org", paths: ["org"] },
+    { kind: "skills", paths: ["skills", "skills.json"] },
+    { kind: "docs", paths: ["docs"] },
+    { kind: "knowledge", paths: ["knowledge"] },
+    { kind: "workflows", paths: ["workflows"] },
+];
+/** The name patterns the walker looks for directly in the home, with the kind each belongs to. */
+export const TOP_LEVEL_FILE_TARGETS = HOME_ARCHIVE_TARGETS
+    .flatMap((target) => ("topLevelFiles" in target ? [{ kind: target.kind, pattern: target.topLevelFiles }] : []));
+export const BACKUP_KINDS = HOME_ARCHIVE_TARGETS.map((target) => target.kind);
+/**
+ * Reproducible caches and nested checkouts, skipped at any depth. A skill that
+ * vendors its own clone or virtualenv can outweigh the rest of the home, and
+ * none of it is content the operator would lose.
+ */
+export const EXCLUDED_DIRECTORY_NAMES = ["node_modules", ".git", ".venv", "__pycache__"];
+/** The workflow store and its sidecars live beside files worth archiving. */
+const WORKFLOW_DATABASE_FILE = /^workflows\/[^/]+\.db(-wal|-shm|-journal)?$/;
+/** Where the manifest rides inside the archive. Not a home path, so it can never collide with one. */
+export const MANIFEST_ENTRY_PATH = ".backup-manifest.json";
+/** True for a home-relative path the walker must leave out of the archive. */
+export function isExcludedPath(relativePath, isDirectory) {
+    if (isDirectory)
+        return EXCLUDED_DIRECTORY_NAMES.includes(relativePath.split("/").pop() ?? "");
+    return WORKFLOW_DATABASE_FILE.test(relativePath);
+}
+/**
+ * The kind an archive entry belongs to, or null for one no target covers.
+ * `type` matters only for the name patterns: a directory that happens to be
+ * called `drafts.md` is not a document.
+ */
+export function kindOfPath(entryPath, type = "file") {
+    for (const target of HOME_ARCHIVE_TARGETS) {
+        for (const root of target.paths) {
+            if (entryPath === root || entryPath.startsWith(`${root}/`))
+                return target.kind;
+        }
+    }
+    if (type === "directory")
+        return null;
+    return TOP_LEVEL_FILE_TARGETS.find(({ pattern }) => pattern.test(entryPath))?.kind ?? null;
+}
+/**
+ * Why an archive entry path must not be trusted, or null when it is the plain
+ * relative form the writer produces. Anything else - absolute, climbing out with
+ * `..`, or merely not canonical - is refused rather than normalized: a path that
+ * needs interpreting is a path that can be interpreted two ways.
+ */
+export function unsafePathReason(entryPath) {
+    if (entryPath === "")
+        return "empty";
+    if (entryPath.includes("\0"))
+        return "contains a NUL byte";
+    if (entryPath.startsWith("/"))
+        return "absolute";
+    // On Windows a backslash separates and a colon names a drive; on POSIX both
+    // are ordinary characters a real file may carry.
+    if (path.sep === "\\" && /[\\:]/.test(entryPath))
+        return "contains a Windows path separator or drive";
+    for (const segment of entryPath.split("/")) {
+        if (segment === "")
+            return "contains an empty segment";
+        if (segment === "." || segment === "..")
+            return `contains a "${segment}" segment`;
+    }
+    return null;
+}
+//# sourceMappingURL=targets.js.map

package/dist/src/backup/targets.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"targets.js","sourceRoot":"","sources":["../../../src/backup/targets.ts"],"names":[],"mappings":"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"}

package/dist/src/backup/walk.d.ts

@@ -0,0 +1,42 @@
+import { type ArchiveLimits } from "./limits.js";
+import type { SkippedEntry } from "./manifest.js";
+/** One thing in the home the archive will carry. */
+export interface HomeEntry {
+    /** Home-relative, slash-separated. */
+    path: string;
+    type: "file" | "directory" | "symlink";
+    mode: number;
+    size: number;
+    mtimeSeconds: number;
+    linkTarget?: string;
+}
+export interface HomeWalk {
+    /** Sorted by path, so a directory always precedes what it holds. */
+    entries: HomeEntry[];
+    /** Bytes of file content among them. */
+    bytes: number;
+    /** The first of what was left out; `skippedCount` is how many there were. */
+    skipped: SkippedEntry[];
+    skippedCount: number;
+    warnings: string[];
+}
+export declare function absolutePathOf(home: string, relativePath: string): string;
+export interface CollectOptions {
+    excludePaths?: string[];
+    limits: ArchiveLimits;
+    /**
+     * Home-relative paths to take instead of everything under the archive
+     * targets. Nothing else in the home is so much as listed, so a home that as
+     * a whole is far past `limits` can still have a few of its files collected.
+     */
+    only?: readonly string[];
+}
+/**
+ * Lists everything under the archive targets of `home`, without following a
+ * single symlink, and gives up with {@link ArchiveTooLargeError} as soon as it
+ * has seen more than `limits` allow. Asynchronous throughout: this runs inside
+ * the gateway once a day, and a home with a great many files must not stall it
+ * while they are counted.
+ */
+export declare function collectHomeEntries(home: string, options: CollectOptions): Promise<HomeWalk>;
+//# sourceMappingURL=walk.d.ts.map

package/dist/src/backup/walk.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"walk.d.ts","sourceRoot":"","sources":["../../../src/backup/walk.ts"],"names":[],"mappings":"AAGA,OAAO,EAA2D,KAAK,aAAa,EAAE,MAAM,aAAa,CAAC;AAC1G,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAGlD,oDAAoD;AACpD,MAAM,WAAW,SAAS;IACxB,sCAAsC;IACtC,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,GAAG,WAAW,GAAG,SAAS,CAAC;IACvC,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,YAAY,EAAE,MAAM,CAAC;IACrB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,QAAQ;IACvB,oEAAoE;IACpE,OAAO,EAAE,SAAS,EAAE,CAAC;IACrB,wCAAwC;IACxC,KAAK,EAAE,MAAM,CAAC;IACd,6EAA6E;IAC7E,OAAO,EAAE,YAAY,EAAE,CAAC;IACxB,YAAY,EAAE,MAAM,CAAC;IACrB,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAkBD,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,MAAM,CAEzE;AA4QD,MAAM,WAAW,cAAc;IAC7B,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IACxB,MAAM,EAAE,aAAa,CAAC;IACtB;;;;OAIG;IACH,IAAI,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAC1B;AAED;;;;;;GAMG;AACH,wBAAsB,kBAAkB,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,QAAQ,CAAC,CA+BjG"}