@vdoninja/ninja-p2p 0.1.1 → 0.1.2

package/dist/file-transfer.d.ts

@@ -0,0 +1,54 @@
+import { type FileAckPayload, type FileChunkPayload, type FileCompletePayload, type FileOfferPayload, type FileTransferKind, type PeerIdentity } from "./protocol.js";
+import type { VDOBridge } from "./vdo-bridge.js";
+export declare const DEFAULT_TRANSFER_CHUNK_SIZE = 12000;
+export type PreparedFileTransfer = {
+    name: string;
+    filePath: string;
+    mimeType: string;
+    kind: FileTransferKind;
+    bytes: Uint8Array;
+    size: number;
+    sha256: string;
+};
+export type IncomingTransferManifest = {
+    transferId: string;
+    from: PeerIdentity;
+    name: string;
+    safeName: string;
+    mimeType: string;
+    kind: FileTransferKind;
+    size: number;
+    sha256: string;
+    chunkSize: number;
+    totalChunks: number;
+    receivedChunks: number;
+    receivedBytes: number;
+    tempPath: string;
+    savedPath: string;
+    createdAt: number;
+    updatedAt: number;
+    completedAt?: number;
+};
+export type CompletedTransferResult = {
+    transferId: string;
+    name: string;
+    mimeType: string;
+    kind: FileTransferKind;
+    size: number;
+    sha256: string;
+    savedPath: string;
+};
+export declare function prepareFileTransferFromPath(filePath: string, kind?: FileTransferKind): PreparedFileTransfer;
+export declare function sendPreparedFileTransfer(bridge: VDOBridge, targetStreamId: string, prepared: PreparedFileTransfer, chunkSize?: number): FileOfferPayload;
+export declare function sendFileFromPath(bridge: VDOBridge, targetStreamId: string, filePath: string, kind?: FileTransferKind, chunkSize?: number): FileOfferPayload;
+export declare function beginIncomingTransfer(stateDir: string, from: PeerIdentity, offer: FileOfferPayload): IncomingTransferManifest;
+export declare function appendIncomingTransferChunk(stateDir: string, payload: FileChunkPayload): IncomingTransferManifest;
+export declare function completeIncomingTransfer(stateDir: string, payload: FileCompletePayload): CompletedTransferResult;
+export declare function createFileAckPayload(result: CompletedTransferResult): FileAckPayload;
+export declare function createFailedFileAckPayload(transferId: string, error: unknown): FileAckPayload;
+export declare function readTransferManifest(stateDir: string, transferId: string): IncomingTransferManifest | null;
+export declare function sha256Hex(bytes: Uint8Array): string;
+export declare function bytesToBase64(bytes: Uint8Array): string;
+export declare function base64ToBytes(value: string): Uint8Array;
+export declare function readSavedTransferBytes(savedPath: string): Uint8Array;
+export declare function getSavedTransferSize(savedPath: string): number;

package/dist/file-transfer.js

@@ -0,0 +1,241 @@
+import { appendFileSync, existsSync, mkdirSync, readFileSync, renameSync, statSync, writeFileSync, } from "node:fs";
+import path from "node:path";
+import { createHash } from "node:crypto";
+import { createMessageId, } from "./protocol.js";
+export const DEFAULT_TRANSFER_CHUNK_SIZE = 12_000;
+export function prepareFileTransferFromPath(filePath, kind = "file") {
+    const resolved = path.resolve(filePath);
+    const bytes = new Uint8Array(readFileSync(resolved));
+    const name = path.basename(resolved);
+    return {
+        name,
+        filePath: resolved,
+        mimeType: guessMimeType(name, kind),
+        kind,
+        bytes,
+        size: bytes.byteLength,
+        sha256: sha256Hex(bytes),
+    };
+}
+export function sendPreparedFileTransfer(bridge, targetStreamId, prepared, chunkSize = DEFAULT_TRANSFER_CHUNK_SIZE) {
+    if (!bridge.isConnected()) {
+        throw new Error("bridge is not connected");
+    }
+    if (!bridge.peers.isConnected(targetStreamId)) {
+        throw new Error(`peer is not connected: ${targetStreamId}`);
+    }
+    const normalizedChunkSize = Math.max(1_024, chunkSize);
+    const totalChunks = prepared.size === 0 ? 0 : Math.ceil(prepared.size / normalizedChunkSize);
+    const transferId = createMessageId();
+    const offer = {
+        transferId,
+        name: prepared.name,
+        mimeType: prepared.mimeType,
+        kind: prepared.kind,
+        size: prepared.size,
+        sha256: prepared.sha256,
+        chunkSize: normalizedChunkSize,
+        totalChunks,
+    };
+    bridge.bus.send(targetStreamId, "file_offer", offer);
+    for (let index = 0; index < totalChunks; index += 1) {
+        const start = index * normalizedChunkSize;
+        const end = Math.min(start + normalizedChunkSize, prepared.size);
+        const chunk = prepared.bytes.slice(start, end);
+        const payload = {
+            transferId,
+            index,
+            totalChunks,
+            data: bytesToBase64(chunk),
+        };
+        bridge.bus.send(targetStreamId, "file_chunk", payload);
+    }
+    bridge.bus.send(targetStreamId, "file_complete", {
+        transferId,
+        totalChunks,
+        size: prepared.size,
+        sha256: prepared.sha256,
+    });
+    return offer;
+}
+export function sendFileFromPath(bridge, targetStreamId, filePath, kind = "file", chunkSize = DEFAULT_TRANSFER_CHUNK_SIZE) {
+    return sendPreparedFileTransfer(bridge, targetStreamId, prepareFileTransferFromPath(filePath, kind), chunkSize);
+}
+export function beginIncomingTransfer(stateDir, from, offer) {
+    const paths = getTransferPaths(stateDir, offer.transferId);
+    mkdirSync(paths.transfersDir, { recursive: true });
+    mkdirSync(paths.downloadsDir, { recursive: true });
+    const existing = readTransferManifest(stateDir, offer.transferId);
+    if (existing) {
+        return existing;
+    }
+    writeFileSync(paths.tempPath, new Uint8Array(0));
+    const safeName = sanitizeFileName(offer.name);
+    const manifest = {
+        transferId: offer.transferId,
+        from,
+        name: offer.name,
+        safeName,
+        mimeType: offer.mimeType,
+        kind: offer.kind,
+        size: offer.size,
+        sha256: offer.sha256,
+        chunkSize: offer.chunkSize,
+        totalChunks: offer.totalChunks,
+        receivedChunks: 0,
+        receivedBytes: 0,
+        tempPath: paths.tempPath,
+        savedPath: chooseSavedPath(paths.downloadsDir, safeName, offer.transferId),
+        createdAt: Date.now(),
+        updatedAt: Date.now(),
+    };
+    writeManifest(paths.manifestPath, manifest);
+    return manifest;
+}
+export function appendIncomingTransferChunk(stateDir, payload) {
+    const manifest = mustReadTransferManifest(stateDir, payload.transferId);
+    if (manifest.completedAt) {
+        return manifest;
+    }
+    if (payload.index !== manifest.receivedChunks) {
+        throw new Error(`unexpected chunk index ${payload.index}; expected ${manifest.receivedChunks}`);
+    }
+    if (payload.totalChunks !== manifest.totalChunks) {
+        throw new Error(`unexpected totalChunks ${payload.totalChunks}; expected ${manifest.totalChunks}`);
+    }
+    const bytes = base64ToBytes(payload.data);
+    appendFileSync(manifest.tempPath, bytes);
+    manifest.receivedChunks += 1;
+    manifest.receivedBytes += bytes.byteLength;
+    manifest.updatedAt = Date.now();
+    writeManifest(getTransferPaths(stateDir, payload.transferId).manifestPath, manifest);
+    return manifest;
+}
+export function completeIncomingTransfer(stateDir, payload) {
+    const manifest = mustReadTransferManifest(stateDir, payload.transferId);
+    if (!manifest.completedAt) {
+        if (payload.totalChunks !== manifest.totalChunks) {
+            throw new Error(`unexpected totalChunks ${payload.totalChunks}; expected ${manifest.totalChunks}`);
+        }
+        if (manifest.receivedChunks !== manifest.totalChunks) {
+            throw new Error(`transfer incomplete: received ${manifest.receivedChunks}/${manifest.totalChunks} chunks`);
+        }
+        if (manifest.receivedBytes !== manifest.size || payload.size !== manifest.size) {
+            throw new Error(`transfer size mismatch: received ${manifest.receivedBytes}, expected ${manifest.size}`);
+        }
+        const bytes = new Uint8Array(readFileSync(manifest.tempPath));
+        const sha256 = sha256Hex(bytes);
+        if (sha256 !== manifest.sha256 || payload.sha256 !== manifest.sha256) {
+            throw new Error("transfer sha256 mismatch");
+        }
+        renameSync(manifest.tempPath, manifest.savedPath);
+        manifest.completedAt = Date.now();
+        manifest.updatedAt = manifest.completedAt;
+        writeManifest(getTransferPaths(stateDir, payload.transferId).manifestPath, manifest);
+    }
+    return {
+        transferId: manifest.transferId,
+        name: manifest.name,
+        mimeType: manifest.mimeType,
+        kind: manifest.kind,
+        size: manifest.size,
+        sha256: manifest.sha256,
+        savedPath: manifest.savedPath,
+    };
+}
+export function createFileAckPayload(result) {
+    return {
+        transferId: result.transferId,
+        ok: true,
+        name: result.name,
+        mimeType: result.mimeType,
+        kind: result.kind,
+        size: result.size,
+        sha256: result.sha256,
+        savedPath: result.savedPath,
+    };
+}
+export function createFailedFileAckPayload(transferId, error) {
+    return {
+        transferId,
+        ok: false,
+        error: error instanceof Error ? error.message : String(error),
+    };
+}
+export function readTransferManifest(stateDir, transferId) {
+    const manifestPath = getTransferPaths(stateDir, transferId).manifestPath;
+    if (!existsSync(manifestPath))
+        return null;
+    return JSON.parse(readFileSync(manifestPath, "utf8"));
+}
+function mustReadTransferManifest(stateDir, transferId) {
+    const manifest = readTransferManifest(stateDir, transferId);
+    if (!manifest) {
+        throw new Error(`unknown transfer: ${transferId}`);
+    }
+    return manifest;
+}
+function getTransferPaths(stateDir, transferId) {
+    const transfersDir = path.join(path.resolve(stateDir), "transfers");
+    const downloadsDir = path.join(path.resolve(stateDir), "downloads");
+    return {
+        transfersDir,
+        downloadsDir,
+        manifestPath: path.join(transfersDir, `${transferId}.json`),
+        tempPath: path.join(transfersDir, `${transferId}.part`),
+    };
+}
+function writeManifest(manifestPath, manifest) {
+    writeFileSync(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`, "utf8");
+}
+function chooseSavedPath(downloadsDir, safeName, transferId) {
+    const parsed = path.parse(safeName);
+    const base = parsed.name || "download";
+    const ext = parsed.ext || "";
+    const direct = path.join(downloadsDir, safeName || `download_${transferId}`);
+    if (!existsSync(direct)) {
+        return direct;
+    }
+    return path.join(downloadsDir, `${base}_${transferId}${ext}`);
+}
+function sanitizeFileName(name) {
+    const base = path.basename(name || "download");
+    return base.replace(/[<>:"/\\|?*\x00-\x1F]/g, "_") || "download";
+}
+function guessMimeType(name, kind) {
+    const ext = path.extname(name).toLowerCase();
+    const known = {
+        ".png": "image/png",
+        ".jpg": "image/jpeg",
+        ".jpeg": "image/jpeg",
+        ".gif": "image/gif",
+        ".webp": "image/webp",
+        ".svg": "image/svg+xml",
+        ".txt": "text/plain",
+        ".md": "text/markdown",
+        ".json": "application/json",
+        ".pdf": "application/pdf",
+        ".zip": "application/zip",
+        ".gz": "application/gzip",
+        ".tar": "application/x-tar",
+        ".wav": "audio/wav",
+        ".mp3": "audio/mpeg",
+        ".mp4": "video/mp4",
+    };
+    return known[ext] ?? (kind === "image" ? "image/*" : "application/octet-stream");
+}
+export function sha256Hex(bytes) {
+    return createHash("sha256").update(bytes).digest("hex");
+}
+export function bytesToBase64(bytes) {
+    return Buffer.from(bytes).toString("base64");
+}
+export function base64ToBytes(value) {
+    return new Uint8Array(Buffer.from(value, "base64"));
+}
+export function readSavedTransferBytes(savedPath) {
+    return new Uint8Array(readFileSync(savedPath));
+}
+export function getSavedTransferSize(savedPath) {
+    return statSync(savedPath).size;
+}

package/dist/index.d.ts

@@ -1,4 +1,7 @@
 export { MessageBus, type KeywordTrigger, type MessageBusOptions, type SendDataFn } from "./message-bus.js";
 export { PeerRegistry, type PeerRecord, type PeerRegistryEvents } from "./peer-registry.js";
-export { createEnvelope, createInstanceId, createMessageId, envelopeToWire, generateRoomName, isValidEnvelope, parseEnvelope, type AnnouncePayload, type MessageEnvelope, type MessageType, type PeerIdentity, type SkillUpdatePayload, } from "./protocol.js";
+export { ensureAgentState, getInboxSummary, isInboxWorthy, listInboxMessages, listQueuedAgentActions, queueAgentAction, readAgentSession, readPeersSnapshot, removeQueuedAgentAction, storeInboxMessage, takeInboxMessages, writeAgentSession, writePeersSnapshot, type AgentSessionState, type InboxMessage, type InboxSummary, type QueuedAgentAction, type QueuedAgentActionInput, } from "./agent-state.js";
+export { DEFAULT_TRANSFER_CHUNK_SIZE, appendIncomingTransferChunk, beginIncomingTransfer, bytesToBase64, completeIncomingTransfer, createFailedFileAckPayload, createFileAckPayload, prepareFileTransferFromPath, readSavedTransferBytes, readTransferManifest, sendFileFromPath, sendPreparedFileTransfer, sha256Hex, type CompletedTransferResult, type IncomingTransferManifest, type PreparedFileTransfer, } from "./file-transfer.js";
+export { createEnvelope, createInstanceId, createMessageId, envelopeToWire, type FileAckPayload, type FileChunkPayload, type FileCompletePayload, type FileOfferPayload, type FileTransferKind, generateRoomName, isValidEnvelope, parseEnvelope, type AgentAsk, type AgentProfile, type AnnouncePayload, type MessageEnvelope, type MessageType, type PeerIdentity, type SharedFolderSummary, type SkillUpdatePayload, } from "./protocol.js";
+export { inferTransferKind, listSharedFolderEntries, parseSharedFolderSpecs, resolveSharedFile, toSharedFolderSummaries, type ResolvedSharedFile, type SharedFolderConfig, type SharedFolderEntry, type SharedFolderListing, } from "./shared-folders.js";
 export { VDOBridge, type VDOBridgeOptions } from "./vdo-bridge.js";

package/dist/index.js

@@ -1,4 +1,7 @@
 export { MessageBus } from "./message-bus.js";
 export { PeerRegistry } from "./peer-registry.js";
+export { ensureAgentState, getInboxSummary, isInboxWorthy, listInboxMessages, listQueuedAgentActions, queueAgentAction, readAgentSession, readPeersSnapshot, removeQueuedAgentAction, storeInboxMessage, takeInboxMessages, writeAgentSession, writePeersSnapshot, } from "./agent-state.js";
+export { DEFAULT_TRANSFER_CHUNK_SIZE, appendIncomingTransferChunk, beginIncomingTransfer, bytesToBase64, completeIncomingTransfer, createFailedFileAckPayload, createFileAckPayload, prepareFileTransferFromPath, readSavedTransferBytes, readTransferManifest, sendFileFromPath, sendPreparedFileTransfer, sha256Hex, } from "./file-transfer.js";
 export { createEnvelope, createInstanceId, createMessageId, envelopeToWire, generateRoomName, isValidEnvelope, parseEnvelope, } from "./protocol.js";
+export { inferTransferKind, listSharedFolderEntries, parseSharedFolderSpecs, resolveSharedFile, toSharedFolderSummaries, } from "./shared-folders.js";
 export { VDOBridge } from "./vdo-bridge.js";

package/dist/message-bus.d.ts

@@ -40,6 +40,7 @@ export declare class MessageBus extends EventEmitter {
     constructor(identity: PeerIdentity, peers: PeerRegistry, options?: MessageBusOptions);
     /** Set the low-level send function (provided by VDOBridge after SDK connects). */
     setSendDataFn(fn: SendDataFn): void;
+    private emitBusError;
     subscribe(topic: string): void;
     unsubscribe(topic: string): void;
     isSubscribed(topic: string): boolean;

package/dist/message-bus.js

@@ -37,6 +37,13 @@ export class MessageBus extends EventEmitter {
     setSendDataFn(fn) {
         this.sendDataFn = fn;
     }
+    emitBusError(err) {
+        if (this.listenerCount("error") > 0) {
+            this.emit("error", err);
+            return;
+        }
+        console.error("[P2P] Message bus error:", err);
+    }
     // ── Subscriptions ────────────────────────────────────────────────────────
     subscribe(topic) {
         this.subscriptions.add(topic);
@@ -186,8 +193,8 @@ export class MessageBus extends EventEmitter {
         }
     }
     addToHistory(envelope) {
-        // Don't store pings/pongs in history
-        if (envelope.type === "ping" || envelope.type === "pong")
+        // Don't store heartbeat or file chunk traffic in history.
+        if (envelope.type === "ping" || envelope.type === "pong" || envelope.type === "file_chunk")
             return;
         this.history.push(envelope);
         while (this.history.length > this.historySize) {
@@ -219,7 +226,7 @@ export class MessageBus extends EventEmitter {
                     trigger.handler(envelope);
                 }
                 catch (err) {
-                    this.emit("error", err);
+                    this.emitBusError(err);
                 }
             }
         }

package/dist/peer-registry.d.ts

@@ -8,7 +8,7 @@
  * Zero dependencies on stevesbot internals.
  */
 import { EventEmitter } from "node:events";
-import type { AnnouncePayload, PeerIdentity, SkillUpdatePayload } from "./protocol.js";
+import type { AgentProfile, AnnouncePayload, PeerIdentity, SkillUpdatePayload } from "./protocol.js";
 export type PeerRecord = {
     streamId: string;
     uuid: string;
@@ -18,6 +18,7 @@ export type PeerRecord = {
     statusDetail: string;
     topics: string[];
     version: string;
+    agentProfile: AgentProfile | null;
     connectedAt: number;
     lastSeenAt: number;
     connected: boolean;

package/dist/peer-registry.js

@@ -44,6 +44,7 @@ export class PeerRegistry extends EventEmitter {
             statusDetail: "",
             topics: [],
             version: "",
+            agentProfile: null,
             connectedAt: Date.now(),
             lastSeenAt: Date.now(),
             connected: true,
@@ -104,6 +105,7 @@ export class PeerRegistry extends EventEmitter {
         peer.statusDetail = announce.statusDetail ?? "";
         peer.topics = announce.topics ?? [];
         peer.version = announce.version ?? "";
+        peer.agentProfile = announce.agent ?? peer.agentProfile;
         peer.lastSeenAt = Date.now();
         this.emit("peer:update", peer, "announce");
         return peer;
@@ -116,6 +118,7 @@ export class PeerRegistry extends EventEmitter {
         peer.skills = update.skills ?? peer.skills;
         peer.status = update.status ?? peer.status;
         peer.statusDetail = update.statusDetail ?? peer.statusDetail;
+        peer.agentProfile = update.agent ?? peer.agentProfile;
         peer.lastSeenAt = Date.now();
         this.emit("peer:update", peer, "skill_update");
         return peer;
@@ -192,6 +195,7 @@ export class PeerRegistry extends EventEmitter {
             skills: p.skills,
             status: p.status,
             statusDetail: p.statusDetail,
+            agentProfile: p.agentProfile,
             connected: p.connected,
             connectedAt: p.connectedAt,
             lastSeenAt: p.lastSeenAt,

package/dist/protocol.d.ts

@@ -5,13 +5,67 @@
  * WebRTC data channels. This module has zero dependencies on stevesbot
  * internals — it can be extracted and reused by any bot.
  */
-export type MessageType = "chat" | "announce" | "skill_update" | "command" | "command_response" | "event" | "ping" | "pong" | "ack" | "history_replay" | "history_request";
+export type MessageType = "chat" | "announce" | "skill_update" | "command" | "command_response" | "file_offer" | "file_chunk" | "file_complete" | "file_ack" | "event" | "ping" | "pong" | "ack" | "history_replay" | "history_request";
 export type PeerIdentity = {
     streamId: string;
     role: string;
     name: string;
     instanceId: string;
 };
+export type AgentAsk = {
+    name: string;
+    description: string;
+    via?: "command" | "chat" | "event";
+    example?: string;
+};
+export type SharedFolderSummary = {
+    name: string;
+    description?: string;
+};
+export type AgentProfile = {
+    runtime?: string;
+    provider?: string;
+    model?: string;
+    summary?: string;
+    workspace?: string;
+    can?: string[];
+    asks?: AgentAsk[];
+    shares?: SharedFolderSummary[];
+};
+export type FileTransferKind = "file" | "image";
+export type FileOfferPayload = {
+    transferId: string;
+    name: string;
+    mimeType: string;
+    kind: FileTransferKind;
+    size: number;
+    sha256: string;
+    chunkSize: number;
+    totalChunks: number;
+};
+export type FileChunkPayload = {
+    transferId: string;
+    index: number;
+    totalChunks: number;
+    data: string;
+};
+export type FileCompletePayload = {
+    transferId: string;
+    totalChunks: number;
+    size: number;
+    sha256: string;
+};
+export type FileAckPayload = {
+    transferId: string;
+    ok: boolean;
+    name?: string;
+    mimeType?: string;
+    kind?: FileTransferKind;
+    size?: number;
+    sha256?: string;
+    savedPath?: string;
+    error?: string;
+};
 export type MessageEnvelope = {
     v: 1;
     id: string;
@@ -28,11 +82,13 @@ export type AnnouncePayload = {
     statusDetail?: string;
     version: string;
     topics: string[];
+    agent?: AgentProfile;
 };
 export type SkillUpdatePayload = {
     skills: string[];
     status: string;
     statusDetail?: string;
+    agent?: AgentProfile;
 };
 /** Generate a short unique message ID. */
 export declare function createMessageId(): string;

package/dist/shared-folders.d.ts

@@ -0,0 +1,31 @@
+import type { FileTransferKind, SharedFolderSummary } from "./protocol.js";
+export type SharedFolderConfig = {
+    name: string;
+    path: string;
+    description?: string;
+};
+export type SharedFolderEntry = {
+    name: string;
+    path: string;
+    type: "dir" | "file";
+    size: number | null;
+};
+export type SharedFolderListing = {
+    share: string;
+    path: string;
+    entries: SharedFolderEntry[];
+    truncated: boolean;
+};
+export type ResolvedSharedFile = {
+    share: string;
+    path: string;
+    filePath: string;
+    name: string;
+    kind: FileTransferKind;
+    size: number;
+};
+export declare function parseSharedFolderSpecs(rawValues: string[], cwd?: string): SharedFolderConfig[];
+export declare function toSharedFolderSummaries(sharedFolders: SharedFolderConfig[]): SharedFolderSummary[];
+export declare function listSharedFolderEntries(sharedFolders: SharedFolderConfig[], shareName: string, relativePath?: string, maxEntries?: number): SharedFolderListing;
+export declare function resolveSharedFile(sharedFolders: SharedFolderConfig[], shareName: string, relativePath: string): ResolvedSharedFile;
+export declare function inferTransferKind(filePath: string): FileTransferKind;

package/dist/shared-folders.js

@@ -0,0 +1,137 @@
+import { existsSync, readdirSync, statSync } from "node:fs";
+import path from "node:path";
+export function parseSharedFolderSpecs(rawValues, cwd = process.cwd()) {
+    const shares = [];
+    const seen = new Set();
+    for (const raw of rawValues.map((value) => value.trim()).filter(Boolean)) {
+        const separatorIndex = raw.indexOf("=");
+        if (separatorIndex <= 0 || separatorIndex === raw.length - 1) {
+            throw new Error(`invalid share spec: ${raw}; use --share name=path`);
+        }
+        const name = raw.slice(0, separatorIndex).trim();
+        const folderPath = raw.slice(separatorIndex + 1).trim();
+        if (!/^[A-Za-z0-9._-]+$/.test(name)) {
+            throw new Error(`invalid share name: ${name}`);
+        }
+        const key = name.toLowerCase();
+        if (seen.has(key)) {
+            throw new Error(`duplicate share name: ${name}`);
+        }
+        const resolved = path.resolve(cwd, folderPath);
+        if (!existsSync(resolved)) {
+            throw new Error(`shared folder does not exist: ${resolved}`);
+        }
+        const stats = statSync(resolved);
+        if (!stats.isDirectory()) {
+            throw new Error(`shared folder is not a directory: ${resolved}`);
+        }
+        seen.add(key);
+        shares.push({
+            name,
+            path: resolved,
+        });
+    }
+    return shares;
+}
+export function toSharedFolderSummaries(sharedFolders) {
+    return sharedFolders.map((share) => {
+        const summary = { name: share.name };
+        if (share.description)
+            summary.description = share.description;
+        return summary;
+    });
+}
+export function listSharedFolderEntries(sharedFolders, shareName, relativePath = "", maxEntries = 200) {
+    const share = requireSharedFolder(sharedFolders, shareName);
+    const resolved = resolveSharedPath(share, relativePath);
+    const stats = statSync(resolved.filePath);
+    if (!stats.isDirectory()) {
+        throw new Error(`shared path is not a directory: ${resolved.path || "."}`);
+    }
+    const entries = readdirSync(resolved.filePath, { withFileTypes: true })
+        .map((entry) => {
+        const childPath = resolved.path ? `${resolved.path}/${entry.name}` : entry.name;
+        const absolutePath = path.join(resolved.filePath, entry.name);
+        if (entry.isDirectory()) {
+            return {
+                name: entry.name,
+                path: childPath,
+                type: "dir",
+                size: null,
+            };
+        }
+        return {
+            name: entry.name,
+            path: childPath,
+            type: "file",
+            size: statSync(absolutePath).size,
+        };
+    })
+        .sort((a, b) => Number(a.type === "file") - Number(b.type === "file") || a.name.localeCompare(b.name));
+    return {
+        share: share.name,
+        path: resolved.path,
+        entries: entries.slice(0, Math.max(1, maxEntries)),
+        truncated: entries.length > maxEntries,
+    };
+}
+export function resolveSharedFile(sharedFolders, shareName, relativePath) {
+    const share = requireSharedFolder(sharedFolders, shareName);
+    const resolved = resolveSharedPath(share, relativePath);
+    const stats = statSync(resolved.filePath);
+    if (!stats.isFile()) {
+        throw new Error(`shared path is not a file: ${resolved.path || "."}`);
+    }
+    return {
+        share: share.name,
+        path: resolved.path,
+        filePath: resolved.filePath,
+        name: path.basename(resolved.filePath),
+        kind: inferTransferKind(resolved.filePath),
+        size: stats.size,
+    };
+}
+export function inferTransferKind(filePath) {
+    const ext = path.extname(filePath).toLowerCase();
+    if ([".png", ".jpg", ".jpeg", ".gif", ".webp", ".svg", ".bmp"].includes(ext)) {
+        return "image";
+    }
+    return "file";
+}
+function requireSharedFolder(sharedFolders, shareName) {
+    const share = sharedFolders.find((item) => item.name.toLowerCase() === shareName.trim().toLowerCase());
+    if (!share) {
+        throw new Error(`unknown share: ${shareName}`);
+    }
+    return share;
+}
+function resolveSharedPath(share, relativePath) {
+    const normalized = normalizeRelativeSharePath(relativePath);
+    const target = path.resolve(share.path, normalized || ".");
+    if (target !== share.path && !target.startsWith(`${share.path}${path.sep}`)) {
+        throw new Error("shared path escapes the declared folder");
+    }
+    if (!existsSync(target)) {
+        throw new Error(`shared path does not exist: ${normalized || "."}`);
+    }
+    return {
+        filePath: target,
+        path: normalized,
+    };
+}
+function normalizeRelativeSharePath(relativePath) {
+    const raw = relativePath.replace(/\\/g, "/").trim();
+    if (!raw)
+        return "";
+    if (raw.startsWith("/")) {
+        throw new Error("shared path must be relative");
+    }
+    const normalized = path.posix.normalize(raw);
+    if (normalized === ".." || normalized.startsWith("../")) {
+        throw new Error("shared path escapes the declared folder");
+    }
+    if (normalized.includes("/../")) {
+        throw new Error("shared path escapes the declared folder");
+    }
+    return normalized === "." ? "" : normalized;
+}