@shardflux/cli 0.18.1 → 0.19.0

package/dist/project-sync-manifest.d.ts

@@ -1,6 +1,4 @@
 import type { FileManifest, FileManifestEntry } from '@shardflux/sdk';
-export declare const MAX_SYNC_FILE_BYTES: number;
-export declare const MAX_SYNC_ENTRIES = 20000;
 export type Manifest = Record<string, FileManifestEntry>;
 export type Common = Record<string, string>;
 export interface SyncChange {
@@ -13,9 +11,25 @@ export declare function excludedSyncPath(path: string): boolean;
 export declare function contentIdentity(entry?: FileManifestEntry): string;
 /** Deletions have an observation timestamp: a detached filesystem has no deletion clock. Ties favor the laptop. */
 export declare function diffManifests(local: Manifest, remote: Manifest, common: Common, observedAt?: number, blocked?: Set<string>): SyncChange[];
+/**
+ * Validates a manifest's wire shape. Any number of entries and any file size are accepted; an entry whose path this
+ * client cannot represent is moved to `manifest.skipped` (reason `unsupported_path`) instead of failing the pass.
+ */
 export declare function parseManifest(manifest: FileManifest): Manifest;
 export declare function projectGit(folder: string, args: string[], signal?: AbortSignal, input?: string): Promise<string>;
-/** Uses the actual Git implementation rather than an approximation of gitignore. */
+/**
+ * Streams Git's NUL-separated path output into `each`: no output buffer and no time bound, so a tree of any size is
+ * listed in full (the signal still cancels it). Exit codes in `ok` count as success (check-ignore exits 1 for none).
+ */
+export declare function projectGitPaths(folder: string, args: string[], each: (path: string) => void, options?: {
+    signal?: AbortSignal;
+    input?: string;
+    ok?: number[];
+}): Promise<void>;
+/**
+ * Uses the actual Git implementation rather than an approximation of gitignore. Any number of paths; a path this
+ * client cannot represent stays in the list and is reported as skipped by `localEntry`.
+ */
 export declare function selectedProjectPaths(folder: string, signal?: AbortSignal): Promise<string[]>;
 export declare function ignoredProjectPaths(folder: string, paths: string[], signal?: AbortSignal): Promise<string[]>;
 /** Refuse parent symlinks, including a tracked file beneath a submodule/link. */
@@ -24,4 +38,18 @@ export type LocalHashCache = Map<string, {
     metadata: string;
     entry: FileManifestEntry;
 }>;
+export type LocalEntry = FileManifestEntry | {
+    path: string;
+    reason: string;
+} | undefined;
+/**
+ * One project file's manifest entry: undefined when it does not exist (ENOENT), `{ path, reason }` when it is skipped
+ * (`unsupported_type`: a socket, device or FIFO; `unsupported_path`: a name the sync cannot carry, such as one with a
+ * backslash; `nested_repository`: a submodule or nested Git repository). Any size is hashed.
+ */
+export declare function localEntry(folder: string, path: string, signal?: AbortSignal, cache?: LocalHashCache): Promise<FileManifestEntry | {
+    path: string;
+    reason: string;
+} | undefined>;
+/** The cache holds one entry per project path: entries for paths that left the project are dropped after each pass. */
 export declare function localManifest(folder: string, signal?: AbortSignal, cache?: LocalHashCache, known?: string[]): Promise<FileManifest>;

package/dist/project-sync-manifest.js

@@ -1,11 +1,9 @@
 import { createHash } from 'node:crypto';
-import { execFile } from 'node:child_process';
+import { execFile, spawn } from 'node:child_process';
 import { constants } from 'node:fs';
 import { lstat, open, readdir, readlink, realpath } from 'node:fs/promises';
 import { basename, dirname, join, relative, resolve, sep } from 'node:path';
 import { GitError } from "./errors.js";
-export const MAX_SYNC_FILE_BYTES = 64 * 1024 * 1024;
-export const MAX_SYNC_ENTRIES = 20_000;
 export function validSyncPath(path) {
     return path.length > 0 && Buffer.byteLength(path) <= 4096 && !path.includes('\0') && !path.includes('\\') && !path.startsWith('/') && !path.split('/').some((part) => !part || part === '.' || part === '..' || part === '.git' || part === '.shard');
 }
@@ -31,23 +29,33 @@ export function diffManifests(local, remote, common, observedAt = Date.now(), bl
     }
     return changes;
 }
+/**
+ * Validates a manifest's wire shape. Any number of entries and any file size are accepted; an entry whose path this
+ * client cannot represent is moved to `manifest.skipped` (reason `unsupported_path`) instead of failing the pass.
+ */
 export function parseManifest(manifest) {
-    if (!manifest || !Array.isArray(manifest.entries) || !Array.isArray(manifest.skipped) || manifest.entries.length + manifest.skipped.length > MAX_SYNC_ENTRIES)
+    if (!manifest || !Array.isArray(manifest.entries) || !Array.isArray(manifest.skipped))
         throw new Error('invalid project manifest');
     const entries = Object.create(null);
     for (const entry of manifest.entries) {
-        if (!validSyncPath(entry.path) || !/^[a-f0-9]{64}$/.test(entry.sha256) || !Number.isSafeInteger(entry.size) || entry.size < 0 || entry.size > MAX_SYNC_FILE_BYTES || !Number.isInteger(entry.mode) || entry.mode < 0 || entry.mode > 0o777 || !Number.isFinite(entry.mtime_unix_ms) || typeof entry.symlink !== 'boolean' || typeof entry.link_target !== 'string' || entries[entry.path])
-            throw new Error(`invalid project manifest entry: ${entry.path}`);
+        if (typeof entry?.path !== 'string' || !/^[a-f0-9]{64}$/.test(entry.sha256) || !Number.isSafeInteger(entry.size) || entry.size < 0 || !Number.isInteger(entry.mode) || entry.mode < 0 || entry.mode > 0o777 || !Number.isFinite(entry.mtime_unix_ms) || typeof entry.symlink !== 'boolean' || typeof entry.link_target !== 'string' || entries[entry.path])
+            throw new Error(`invalid project manifest entry: ${String(entry?.path)}`);
+        if (!validSyncPath(entry.path)) {
+            manifest.skipped.push({ path: entry.path, reason: 'unsupported_path' });
+            continue;
+        }
         entries[entry.path] = entry;
     }
     for (const skip of manifest.skipped)
-        if (!validSyncPath(skip.path) || typeof skip.reason !== 'string' || !skip.reason)
+        if (typeof skip?.path !== 'string' || !skip.path || typeof skip.reason !== 'string' || !skip.reason)
             throw new Error('invalid skipped project path');
     return entries;
 }
+const GIT_CONFIG = ['-c', 'core.fsmonitor=false', '-c', 'core.untrackedCache=false', '-c', 'core.hooksPath=/dev/null'];
+const gitEnv = () => ({ ...process.env, GIT_TERMINAL_PROMPT: '0', GIT_OPTIONAL_LOCKS: '0' });
 export async function projectGit(folder, args, signal, input = '') {
     return new Promise((resolve, reject) => {
-        const child = execFile('git', ['-C', folder, '-c', 'core.fsmonitor=false', '-c', 'core.untrackedCache=false', '-c', 'core.hooksPath=/dev/null', ...args], { encoding: 'utf8', timeout: 30_000, maxBuffer: 4 << 20, signal, env: { ...process.env, GIT_TERMINAL_PROMPT: '0', GIT_OPTIONAL_LOCKS: '0' } }, (error, stdout, stderr) => {
+        const child = execFile('git', ['-C', folder, ...GIT_CONFIG, ...args], { encoding: 'utf8', timeout: 30_000, maxBuffer: 4 << 20, signal, env: gitEnv() }, (error, stdout, stderr) => {
             if (!error) {
                 resolve(stdout);
                 return;
@@ -65,7 +73,64 @@ export async function projectGit(folder, args, signal, input = '') {
         child.stdin?.end(input);
     });
 }
-/** Uses the actual Git implementation rather than an approximation of gitignore. */
+/**
+ * Streams Git's NUL-separated path output into `each`: no output buffer and no time bound, so a tree of any size is
+ * listed in full (the signal still cancels it). Exit codes in `ok` count as success (check-ignore exits 1 for none).
+ */
+export async function projectGitPaths(folder, args, each, options = {}) {
+    const { signal, input } = options;
+    await new Promise((resolve, reject) => {
+        const child = spawn('git', ['-C', folder, ...GIT_CONFIG, ...args], { stdio: [input === undefined ? 'ignore' : 'pipe', 'pipe', 'pipe'], signal, env: gitEnv() });
+        let pending, stderr = '', failed;
+        const { stdout, stderr: errors } = child;
+        if (!stdout || !errors)
+            throw new Error('git started without output pipes');
+        stdout.on('data', (chunk) => {
+            let at = 0;
+            for (let nul = chunk.indexOf(0); nul >= 0; nul = chunk.indexOf(0, at)) {
+                const part = pending ? Buffer.concat([pending, chunk.subarray(at, nul)]) : chunk.subarray(at, nul);
+                pending = undefined;
+                at = nul + 1;
+                if (part.length)
+                    try {
+                        each(part.toString('utf8'));
+                    }
+                    catch (error) {
+                        failed ??= error instanceof Error ? error : new Error(String(error));
+                        child.kill();
+                    }
+            }
+            if (at < chunk.length)
+                pending = pending ? Buffer.concat([pending, chunk.subarray(at)]) : Buffer.from(chunk.subarray(at));
+        });
+        errors.on('data', (chunk) => { if (stderr.length < 64 << 10)
+            stderr += chunk.toString('utf8'); });
+        child.stdin?.on('error', () => undefined);
+        child.stdin?.end(input);
+        child.once('error', (error) => { reject(signal?.aborted ? error : new GitError(folder, Object.assign(error, { stderr }))); });
+        child.once('close', (code) => {
+            if (failed) {
+                reject(failed);
+                return;
+            }
+            if (signal?.aborted) {
+                reject(signal.reason);
+                return;
+            }
+            if ((options.ok ?? [0]).includes(code ?? -1)) {
+                if (pending?.length)
+                    each(pending.toString('utf8'));
+                resolve();
+                return;
+            }
+            reject(new GitError(folder, Object.assign(new Error(`git ${args[0] ?? ''} exited with ${code}`), { code: code ?? undefined, stderr })));
+        });
+    });
+}
+/**
+ * Uses the actual Git implementation rather than an approximation of gitignore. Any number of paths; a path this
+ * client cannot represent stays in the list and is reported as skipped by `localEntry`.
+ */
 export async function selectedProjectPaths(folder, signal) {
     let git = false;
     try {
@@ -77,13 +142,12 @@ export async function selectedProjectPaths(folder, signal) {
     }
     const paths = new Set();
     if (git) {
-        for (const path of (await projectGit(folder, ['ls-files', '-z', '--cached', '--others', '--exclude-standard', '--', '.'], signal)).split('\0'))
-            if (path && !excludedSyncPath(path))
-                paths.add(path);
-        for (const path of (await projectGit(folder, ['ls-files', '-z', '--others', '--ignored', '--exclude-standard', '--', '.env*', '**/.env*'], signal)).split('\0')) {
-            if (path && basename(path).startsWith('.env') && !excludedSyncPath(path))
+        await projectGitPaths(folder, ['ls-files', '-z', '--cached', '--others', '--exclude-standard', '--', '.'], (path) => { if (!excludedSyncPath(path))
+            paths.add(path); }, { signal });
+        await projectGitPaths(folder, ['ls-files', '-z', '--others', '--ignored', '--exclude-standard', '--', '.env*', '**/.env*'], (path) => {
+            if (basename(path).startsWith('.env') && !excludedSyncPath(path))
                 paths.add(path);
-        }
+        }, { signal });
     }
     else {
         const walk = async (dir) => {
@@ -96,17 +160,10 @@ export async function selectedProjectPaths(folder, signal) {
                     await walk(path);
                 else
                     paths.add(path);
-                if (paths.size > MAX_SYNC_ENTRIES)
-                    throw new Error(`project exceeds ${MAX_SYNC_ENTRIES} sync entries`);
             }
         };
         await walk('');
     }
-    if (paths.size > MAX_SYNC_ENTRIES)
-        throw new Error(`project exceeds ${MAX_SYNC_ENTRIES} sync entries`);
-    for (const path of paths)
-        if (!validSyncPath(path))
-            throw new Error(`unsupported project path: ${JSON.stringify(path)}`);
     return [...paths].sort();
 }
 export async function ignoredProjectPaths(folder, paths, signal) {
@@ -122,18 +179,9 @@ export async function ignoredProjectPaths(folder, paths, signal) {
         return [];
     }
     const ignored = [];
-    for (let at = 0; at < paths.length; at += 32) {
-        let output;
-        try {
-            output = await projectGit(folder, ['check-ignore', '-z', '--stdin'], signal, paths.slice(at, at + 32).join('\0') + '\0');
-        }
-        catch (error) {
-            const failure = error;
-            if (failure.code !== 1)
-                throw error;
-            output = failure.stdout ?? '';
-        }
-        ignored.push(...output.split('\0').filter(Boolean));
+    // Streamed both ways, so the batch only bounds one stdin string; any number of paths is checked.
+    for (let at = 0; at < paths.length; at += 4096) {
+        await projectGitPaths(folder, ['check-ignore', '-z', '--stdin'], (path) => { ignored.push(path); }, { signal, input: paths.slice(at, at + 4096).join('\0') + '\0', ok: [0, 1] });
     }
     return ignored;
 }
@@ -141,92 +189,128 @@ export async function ignoredProjectPaths(folder, paths, signal) {
 export async function projectFilePath(folder, path) {
     if (!validSyncPath(path))
         throw new Error(`unsafe project path: ${JSON.stringify(path)}`);
-    folder = await realpath(folder);
-    const target = resolve(folder, path);
-    const parent = await realpath(dirname(target));
-    const rel = relative(folder, parent);
-    if (rel === '..' || rel.startsWith(`..${sep}`) || resolve(folder, dirname(path)) !== parent)
-        throw new Error(`project path traverses a symbolic link: ${path}`);
+    return await checkedProjectPath(await realpath(folder), path);
+}
+/** `folder` is already a real path; `parents` memoizes each directory's check within one pass. */
+async function checkedProjectPath(folder, path, parents) {
+    const target = resolve(folder, path), dir = dirname(path);
+    let check = parents?.get(dir);
+    if (!check) {
+        check = (async () => {
+            const parent = await realpath(dirname(target));
+            const rel = relative(folder, parent);
+            if (rel === '..' || rel.startsWith(`..${sep}`) || resolve(folder, dir) !== parent)
+                throw new Error(`project path traverses a symbolic link: ${path}`);
+        })();
+        parents?.set(dir, check);
+    }
+    await check;
     return target;
 }
-export async function localManifest(folder, signal, cache, known = []) {
-    const paths = await selectedProjectPaths(folder, signal);
-    const result = { entries: [], skipped: [] };
-    let next = 0;
-    await Promise.all(Array.from({ length: Math.min(16, paths.length) }, async () => {
-        for (;;) {
-            const path = paths[next++];
-            if (path === undefined)
-                break;
-            signal?.throwIfAborted();
-            let target;
-            let st;
-            try {
-                target = await projectFilePath(folder, path);
-                st = await lstat(target);
-            }
-            catch (error) {
-                if (error.code === 'ENOENT')
-                    continue;
-                throw error;
-            }
-            const metadata = `${st.dev}:${st.ino}:${st.size}:${st.mode}:${st.mtimeMs}:${st.ctimeMs}`;
-            const cached = cache?.get(path);
-            if (cached?.metadata === metadata && st.size <= MAX_SYNC_FILE_BYTES) {
-                result.entries.push(cached.entry);
-                continue;
-            }
-            let sha256, link_target = '';
-            if (st.isSymbolicLink()) {
-                link_target = await readlink(target);
-                sha256 = createHash('sha256').update(`symlink\0${link_target}`).digest('hex');
-            }
-            else if (st.isFile()) {
-                if (st.size > MAX_SYNC_FILE_BYTES) {
-                    result.skipped.push({ path, reason: 'max_file_bytes' });
-                    continue;
-                }
-                const file = await open(target, constants.O_RDONLY | constants.O_NOFOLLOW);
-                try {
-                    const hash = createHash('sha256');
-                    let bytes = 0;
-                    for await (const raw of file.createReadStream({ autoClose: false })) {
-                        const chunk = raw;
-                        signal?.throwIfAborted();
-                        bytes += chunk.length;
-                        if (bytes > MAX_SYNC_FILE_BYTES)
-                            throw new Error(`${path} grew beyond the sync limit`);
-                        hash.update(chunk);
-                    }
-                    const after = await file.stat();
-                    if (bytes !== st.size || after.ino !== st.ino || after.mtimeMs !== st.mtimeMs || after.ctimeMs !== st.ctimeMs)
-                        throw new Error(`${path} changed while hashing; retry project sync`);
-                    sha256 = hash.digest('hex');
-                }
-                finally {
-                    await file.close();
-                }
+/** Files at most this size are hashed from one read; larger ones stream through a fixed buffer. */
+const ONE_READ_BYTES = 1 << 20;
+async function entryAt(folder, path, signal, cache, parents) {
+    // `git ls-files --others` lists an untracked nested repository as "dir/"; its files belong to that repository.
+    if (path.endsWith('/') && validSyncPath(path.slice(0, -1)))
+        return { path: path.slice(0, -1), reason: 'nested_repository' };
+    if (!validSyncPath(path))
+        return { path, reason: 'unsupported_path' };
+    signal?.throwIfAborted();
+    let target;
+    let st;
+    try {
+        target = await checkedProjectPath(folder, path, parents);
+        st = await lstat(target);
+    }
+    catch (error) {
+        if (error.code === 'ENOENT' || error.code === 'ENOTDIR')
+            return undefined;
+        throw error;
+    }
+    const metadata = `${st.dev}:${st.ino}:${st.size}:${st.mode}:${st.mtimeMs}:${st.ctimeMs}`;
+    const cached = cache?.get(path);
+    if (cached?.metadata === metadata)
+        return cached.entry;
+    let sha256, link_target = '';
+    if (st.isSymbolicLink()) {
+        link_target = await readlink(target);
+        sha256 = createHash('sha256').update(`symlink\0${link_target}`).digest('hex');
+    }
+    else if (st.isFile()) {
+        // Any size: hashed through a bounded buffer, never held whole.
+        const file = await open(target, constants.O_RDONLY | constants.O_NOFOLLOW);
+        try {
+            const hash = createHash('sha256');
+            let bytes = 0;
+            if (st.size <= ONE_READ_BYTES) {
+                const data = await file.readFile();
+                bytes = data.length;
+                hash.update(data);
             }
             else {
-                result.skipped.push({ path, reason: 'unsupported_type' });
-                continue;
-            }
-            const entry = { path, sha256, size: st.size, mode: st.mode & 0o777, mtime_unix_ms: st.mtimeMs, symlink: st.isSymbolicLink(), link_target };
-            result.entries.push(entry);
-            if (cache) {
-                if (cache.size >= MAX_SYNC_ENTRIES)
-                    cache.clear();
-                cache.set(path, { metadata, entry });
+                const buffer = Buffer.allocUnsafe(ONE_READ_BYTES);
+                for (;;) {
+                    signal?.throwIfAborted();
+                    const { bytesRead } = await file.read(buffer, 0, buffer.length, bytes);
+                    if (!bytesRead)
+                        break;
+                    hash.update(buffer.subarray(0, bytesRead));
+                    bytes += bytesRead;
+                }
             }
+            const after = await file.stat();
+            if (bytes !== st.size || after.ino !== st.ino || after.mtimeMs !== st.mtimeMs || after.ctimeMs !== st.ctimeMs)
+                throw new Error(`${path} changed while hashing; retry project sync`);
+            sha256 = hash.digest('hex');
         }
+        finally {
+            await file.close();
+        }
+    }
+    else
+        return { path, reason: st.isDirectory() ? 'nested_repository' : 'unsupported_type' };
+    const entry = { path, sha256, size: st.size, mode: st.mode & 0o777, mtime_unix_ms: st.mtimeMs, symlink: st.isSymbolicLink(), link_target };
+    cache?.set(path, { metadata, entry });
+    return entry;
+}
+/**
+ * One project file's manifest entry: undefined when it does not exist (ENOENT), `{ path, reason }` when it is skipped
+ * (`unsupported_type`: a socket, device or FIFO; `unsupported_path`: a name the sync cannot carry, such as one with a
+ * backslash; `nested_repository`: a submodule or nested Git repository). Any size is hashed.
+ */
+export async function localEntry(folder, path, signal, cache) {
+    return await entryAt(await realpath(folder), path, signal, cache);
+}
+/** The cache holds one entry per project path: entries for paths that left the project are dropped after each pass. */
+export async function localManifest(folder, signal, cache, known = []) {
+    const paths = await selectedProjectPaths(folder, signal);
+    const real = await realpath(folder);
+    const parents = new Map();
+    const found = new Array(paths.length);
+    let next = 0;
+    await Promise.all(Array.from({ length: Math.min(16, paths.length) }, async () => {
+        for (let at = next++; at < paths.length; at = next++)
+            found[at] = await entryAt(real, paths[at], signal, cache, parents);
     }));
+    const result = { entries: [], skipped: [] };
+    for (const item of found) {
+        if (!item)
+            continue;
+        if ('sha256' in item)
+            result.entries.push(item);
+        else
+            result.skipped.push(item);
+    }
     const selected = new Set(paths);
+    if (cache)
+        for (const path of cache.keys())
+            if (!selected.has(path))
+                cache.delete(path);
     for (const path of known)
         if (!validSyncPath(path))
             throw new Error('invalid common sync path');
     for (const path of await ignoredProjectPaths(folder, known.filter((path) => !selected.has(path)), signal))
         result.skipped.push({ path, reason: 'ignored' });
-    result.entries.sort((a, b) => a.path.localeCompare(b.path));
-    result.skipped.sort((a, b) => a.path.localeCompare(b.path));
+    result.skipped.sort((a, b) => a.path < b.path ? -1 : a.path > b.path ? 1 : 0);
     return result;
 }

package/dist/project-sync-transfer.d.ts

@@ -1,14 +1,60 @@
-import type { CellClient, FileManifestEntry } from '@shardflux/sdk';
+import type { CellClient, FileManifest, FileManifestEntry } from '@shardflux/sdk';
 export type SyncCell = Pick<CellClient, 'files' | 'exec'>;
+/** What blob transfers need: appending writes, ranged reads. */
+type BlobWriteCell = {
+    files: Pick<CellClient['files'], 'write'>;
+};
+type BlobReadCell = {
+    files: Pick<CellClient['files'], 'read'>;
+};
 export interface SyncFile {
     entry: FileManifestEntry;
     data: Uint8Array;
 }
+/** One request's worth of file data. A file larger than this streams through its own archive, one chunk at a time. */
 export declare const SYNC_CHUNK_BYTES: number;
+/** Small files per batch archive (and at most SYNC_CHUNK_BYTES of their data). */
+export declare const SYNC_BATCH_FILES = 128;
 export declare function verifySyncBytes(entry: FileManifestEntry, data: Uint8Array): void;
+/** A small file's verified bytes (whole in memory: callers stream anything above SYNC_CHUNK_BYTES). */
 export declare function readLocalSyncFile(folder: string, entry: FileManifestEntry): Promise<SyncFile>;
-export declare function readRemoteSyncFile(cell: SyncCell, root: string, entry: FileManifestEntry): Promise<SyncFile>;
+/** Applies a file already in memory (or deletes `path` when `file` is undefined). `expected` is the local version it replaces. */
 export declare function applyLocalSyncFile(folder: string, path: string, file: SyncFile | undefined, expected?: FileManifestEntry): Promise<void>;
+/**
+ * Applies the VM's version of one file here (or deletes it when `entry` is undefined), streaming it chunk by chunk
+ * into a temporary file next to the target: any size, never whole in memory. The bytes must hash to `entry`.
+ * `from` reads another VM path (a conflict copy); `expected` is the local version it replaces.
+ */
+export declare function pullRemoteFile(cell: SyncCell, root: string, folder: string, path: string, entry: FileManifestEntry | undefined, options?: {
+    expected?: FileManifestEntry;
+    from?: string;
+    signal?: AbortSignal;
+}): Promise<void>;
+/** Copies a local file to another project path (a conflict copy), verified against `entry`; any size. */
+export declare function copyLocalSyncFile(folder: string, entry: FileManifestEntry, to: string): Promise<void>;
 export declare const APPLY_SYNC_TAR: string;
-export declare function writeSyncBlob(cell: SyncCell, path: string, data: Uint8Array): Promise<void>;
-export declare function applyRemoteSyncBatch(cell: SyncCell, root: string, files: Map<string, SyncFile | undefined>, expected: Record<string, FileManifestEntry | undefined>, signal?: AbortSignal): Promise<void>;
+export declare function writeSyncBlob(cell: BlobWriteCell, path: string, data: Uint8Array): Promise<void>;
+/** Uploads a local file of any size to a VM path, SYNC_CHUNK_BYTES at a time straight from disk. */
+export declare function writeSyncFileFrom(cell: BlobWriteCell, path: string, local: string, signal?: AbortSignal): Promise<void>;
+/** Downloads a VM file of `size` bytes to a new local file, SYNC_CHUNK_BYTES at a time. */
+export declare function readSyncFileTo(cell: BlobReadCell, path: string, size: number, local: string, signal?: AbortSignal): Promise<void>;
+/** Copies a file of `size` bytes from one VM to another, SYNC_CHUNK_BYTES at a time. */
+export declare function copySyncBlob(from: BlobReadCell, path: string, size: number, to: BlobWriteCell, target: string, signal?: AbortSignal): Promise<void>;
+/**
+ * Writes local files into the VM project at `root`: `deletions` first, then `files` (manifest entries of `folder`),
+ * small ones batched (at most SYNC_BATCH_FILES and SYNC_CHUNK_BYTES per archive), larger ones streamed from disk one
+ * chunk at a time. Every file is verified against its entry. Without `overwrite`, each VM path must still be the
+ * `expected` version (absent when missing) or the pass fails as changed; `overwrite: true` replaces whatever is there.
+ * A deletion removes the directories it empties, so a directory can become a file.
+ */
+export declare function pushLocalFiles(cell: SyncCell, root: string, folder: string, files: FileManifestEntry[], deletions: string[], options?: {
+    signal?: AbortSignal;
+    overwrite?: boolean;
+    expected?: Record<string, FileManifestEntry | undefined>;
+}): Promise<void>;
+/**
+ * The VM project's manifest with every file hashed, whatever its size: no `maxFileBytes` is sent, and files an
+ * older guest still skips for size (`max_file_bytes`) are hashed in the VM and returned as entries.
+ */
+export declare function remoteManifest(cell: SyncCell, root: string, knownPaths: string[] | undefined, signal?: AbortSignal): Promise<FileManifest>;
+export {};