@nightowne/tas-cli 2.4.1 → 3.0.0

package/src/sync/sync.js

@@ -9,18 +9,24 @@ import { EventEmitter } from 'events';
 import { FileIndex } from '../db/index.js';
 import { hashFile } from '../crypto/encryption.js';
 import { processFile } from '../index.js';
+import { TelegramPool } from '../telegram/pool.js';
+import { backupRemoteManifest } from '../manifest.js';
 
 // Debounce time in ms to batch rapid file changes
 const DEBOUNCE_MS = 1000;
 
-// Ignore patterns
+// Ignore patterns.
+// NOTE: dotfiles are intentionally NOT ignored — TAS is advertised as a
+// vault for `.env` files, SSH keys, etc. Only well-known junk is skipped.
 const IGNORE_PATTERNS = [
-    /^\./, // Hidden files
+    /^\.DS_Store$/, // macOS metadata
+    /^\.git$/, // git dir name
+    /\.git[\/\\]/, // anything inside .git
     /~$/, // Backup files
     /\.swp$/, // Vim swap files
     /\.tmp$/, // Temp files
-    /node_modules/,
-    /\.git/
+    /(^|[\/\\])node_modules([\/\\]|$)/,
+    /(^|[\/\\])\.tas([\/\\]|$)/ // our own data dir if nested
 ];
 
 export class SyncEngine extends EventEmitter {
@@ -33,6 +39,7 @@ export class SyncEngine extends EventEmitter {
         this.watchers = new Map(); // path -> FSWatcher
         this.pendingChanges = new Map(); // path -> timeout
         this.db = null;
+        this.telegramPool = null;
         this.running = false;
     }
 
@@ -42,6 +49,8 @@ export class SyncEngine extends EventEmitter {
     async initialize() {
         this.db = new FileIndex(path.join(this.dataDir, 'index.db'));
         this.db.init();
+        this.telegramPool = new TelegramPool(this.dataDir, this.config.bots);
+        await this.telegramPool.initialize({ includeDisabled: false });
     }
 
     /**
@@ -98,6 +107,7 @@ export class SyncEngine extends EventEmitter {
 
         let uploaded = 0;
         let skipped = 0;
+        const supersededChunks = [];
 
         // Process files with concurrency limit
         const CONCURRENCY = 4;
@@ -129,14 +139,18 @@ export class SyncEngine extends EventEmitter {
                 try {
                     this.emit('file-upload-start', { file: file.relativePath });
 
-                    await processFile(file.path, {
+                    const result = await processFile(file.path, {
                         password: this.password,
                         dataDir: this.dataDir,
                         customName: file.relativePath, // Use relative path as name
                         config: this.config,
+                        telegramPool: this.telegramPool,
+                        updateManifest: false,
+                        replaceExisting: true,
                         limitRate: this.limitRate ? Math.floor(this.limitRate / CONCURRENCY) : null,
                         onProgress: (msg) => this.emit('progress', { file: file.relativePath, message: msg })
                     });
+                    supersededChunks.push(...(result.supersededChunks || []));
 
                     // Update sync state
                     this.db.updateSyncState(folder.id, file.relativePath, hash, file.mtime);
@@ -144,15 +158,10 @@ export class SyncEngine extends EventEmitter {
 
                     this.emit('file-upload-complete', { file: file.relativePath });
                 } catch (err) {
-                    // File might already exist, skip
-                    if (err.message.includes('duplicate')) {
-                        this.db.updateSyncState(folder.id, file.relativePath, hash, file.mtime);
-                        skipped++;
-                    } else {
-                        // Sleep briefly on non-duplicate error (potential rate limits)
-                        await new Promise(r => setTimeout(r, 2000));
-                        this.emit('file-upload-error', { file: file.relativePath, error: err.message });
-                    }
+                    // Sleep briefly on a network/provider error before this
+                    // worker advances; the staged upload remains resumable.
+                    await new Promise(r => setTimeout(r, 2000));
+                    this.emit('file-upload-error', { file: file.relativePath, error: err.message });
                 }
             }
         };
@@ -163,6 +172,22 @@ export class SyncEngine extends EventEmitter {
 
         await Promise.all(promises);
 
+        if (uploaded > 0) {
+            try {
+                await backupRemoteManifest({
+                    dataDir: this.dataDir,
+                    password: this.password,
+                    config: this.config,
+                    telegramPool: this.telegramPool
+                });
+                for (const chunk of supersededChunks) {
+                    try { await this.telegramPool.deleteMessage(chunk.message_id, chunk.bot_id || null); } catch { }
+                }
+            } catch (error) {
+                this.emit('manifest-error', { error: error.message });
+            }
+        }
+
         this.emit('sync-complete', { folder: folderPath, uploaded, skipped });
 
         return { uploaded, skipped };
@@ -224,6 +249,8 @@ export class SyncEngine extends EventEmitter {
                 dataDir: this.dataDir,
                 customName: filename,
                 config: this.config,
+                telegramPool: this.telegramPool,
+                replaceExisting: true,
                 limitRate: this.limitRate,
                 onProgress: (msg) => this.emit('progress', { file: filename, message: msg })
             });
@@ -232,44 +259,88 @@ export class SyncEngine extends EventEmitter {
 
             this.emit('file-upload-complete', { file: filename });
         } catch (err) {
-            if (!err.message.includes('duplicate')) {
-                this.emit('file-upload-error', { file: filename, error: err.message });
-            }
+            this.emit('file-upload-error', { file: filename, error: err.message });
         }
     }
 
     /**
-     * Start watching a folder
+     * Collect all subdirectories under dirPath (including itself).
+     * Used because fs.watch({ recursive: true }) only works on macOS/Windows.
      */
-    watchFolder(folderPath) {
-        if (this.watchers.has(folderPath)) {
-            return; // Already watching
+    _collectDirs(dirPath) {
+        const dirs = [dirPath];
+        let entries;
+        try {
+            entries = fs.readdirSync(dirPath, { withFileTypes: true });
+        } catch {
+            return dirs;
+        }
+        for (const entry of entries) {
+            if (!entry.isDirectory()) continue;
+            if (this.shouldIgnore(entry.name)) continue;
+            dirs.push(...this._collectDirs(path.join(dirPath, entry.name)));
         }
+        return dirs;
+    }
 
-        const watcher = fs.watch(folderPath, { recursive: true }, (event, filename) => {
-            if (filename) {
-                this.handleFileChange(folderPath, filename);
-            }
-        });
+    _watchSingleDir(watchedDir, rootPath) {
+        if (this.watchers.has(watchedDir)) return;
+        let watcher;
+        try {
+            watcher = fs.watch(watchedDir, (event, filename) => {
+                if (!filename) return;
+                const fullPath = path.join(watchedDir, filename);
+                const rel = path.relative(rootPath, fullPath);
+                if (!rel || rel.startsWith('..')) return;
+                // A new subdirectory appeared — start watching it too
+                try {
+                    if (fs.existsSync(fullPath) && fs.statSync(fullPath).isDirectory()) {
+                        if (!this.shouldIgnore(filename)) {
+                            for (const d of this._collectDirs(fullPath)) {
+                                this._watchSingleDir(d, rootPath);
+                            }
+                        }
+                        return;
+                    }
+                } catch { /* fall through to file handling */ }
+                this.handleFileChange(rootPath, rel);
+            });
+        } catch (err) {
+            this.emit('watch-error', { folder: watchedDir, error: err.message });
+            return;
+        }
 
         watcher.on('error', (err) => {
-            this.emit('watch-error', { folder: folderPath, error: err.message });
+            this.emit('watch-error', { folder: watchedDir, error: err.message });
         });
 
-        this.watchers.set(folderPath, watcher);
+        this.watchers.set(watchedDir, watcher);
+    }
+
+    /**
+     * Start watching a folder (recursive on all platforms)
+     */
+    watchFolder(folderPath) {
+        if (!fs.existsSync(folderPath)) return;
+        for (const dir of this._collectDirs(folderPath)) {
+            this._watchSingleDir(dir, folderPath);
+        }
         this.emit('watch-start', { folder: folderPath });
     }
 
     /**
-     * Stop watching a folder
+     * Stop watching a folder (closes the root watcher and any subdir watchers)
      */
     unwatchFolder(folderPath) {
-        const watcher = this.watchers.get(folderPath);
-        if (watcher) {
-            watcher.close();
-            this.watchers.delete(folderPath);
-            this.emit('watch-stop', { folder: folderPath });
+        let stopped = false;
+        for (const [watchedDir, watcher] of [...this.watchers]) {
+            if (watchedDir === folderPath || watchedDir.startsWith(folderPath + path.sep)) {
+                try { watcher.close(); } catch { }
+                this.watchers.delete(watchedDir);
+                stopped = true;
+            }
         }
+        if (stopped) this.emit('watch-stop', { folder: folderPath });
     }
 
     /**

package/src/telegram/client.js

@@ -1,6 +1,6 @@
 /**
  * Telegram Bot client wrapper
- * Uses official Telegram Bot API - 2GB file limit, FREE, no ban risk!
+ * Uses the official Telegram Bot API.
  * Includes exponential backoff retry and rate limiting for production reliability.
  */
 
@@ -49,6 +49,7 @@ export class TelegramClient {
         this.bot = null;
         this.chatId = null;
         this._lastSendTime = 0;
+        this._sendQueue = Promise.resolve();
     }
 
     /**
@@ -86,16 +87,13 @@ export class TelegramClient {
     async waitForChatId(timeout = 120000) {
         return new Promise((resolve, reject) => {
             const pollingBot = new TelegramBot(this.bot.token, { polling: true });
-            let isCompleted = false;
 
             const timer = setTimeout(() => {
-                isCompleted = true;
                 pollingBot.stopPolling();
                 reject(new Error('Timeout waiting for message. Please message your bot on Telegram.'));
             }, timeout);
 
             pollingBot.on('message', (msg) => {
-                isCompleted = true;
                 clearTimeout(timer);
                 pollingBot.stopPolling();
                 this.chatId = msg.chat.id;
@@ -107,13 +105,10 @@ export class TelegramClient {
             });
 
             pollingBot.on('polling_error', (err) => {
-                // Only suppress errors after successful completion or during cleanup
-                // During active polling, log all errors for debugging
-                if (isCompleted && err.message.includes('ETELEGRAM')) {
-                    // Suppress expected cleanup errors
-                    return;
+                // Ignore polling errors during shutdown
+                if (!err.message.includes('ETELEGRAM')) {
+                    console.error('Polling error:', err.message);
                 }
-                console.error('Polling error:', err.message);
             });
         });
     }
@@ -132,7 +127,7 @@ export class TelegramClient {
 
     /**
      * Send a file to the storage chat
-     * Telegram supports up to 2GB for documents!
+     * Send a document through the configured Bot API endpoint.
      * Includes automatic retry with exponential backoff.
      */
     async sendFile(filePath, caption = '', options = {}) {
@@ -146,7 +141,7 @@ export class TelegramClient {
 
         const filename = path.basename(filePath);
 
-        return withRetry(async () => {
+        const operation = async () => withRetry(async () => {
             await this._rateLimit();
 
             let fileStream = fs.createReadStream(filePath);
@@ -169,6 +164,12 @@ export class TelegramClient {
                 timestamp: message.date
             };
         }, `Upload ${filename}`);
+
+        // Serialize sends per bot/chat. Without a queue, concurrent sync
+        // workers all pass the timestamp check together and burst the API.
+        const queued = this._sendQueue.then(operation, operation);
+        this._sendQueue = queued.catch(() => { });
+        return queued;
     }
 
     /**

package/src/telegram/pool.js

@@ -0,0 +1,105 @@
+/**
+ * Multi-bot routing for TAS.
+ *
+ * A bot is a storage endpoint, not a durability boundary: Telegram controls
+ * every endpoint. Bot IDs are persisted with each chunk so reads and deletes
+ * always go back through the bot that created the Telegram file ID.
+ */
+
+import crypto from 'crypto';
+import { TelegramClient } from './client.js';
+
+export const MULTI_BOT_WARNING =
+    'Experimental: multiple bots do not guarantee extra quota, durability, ban avoidance, or Terms compliance. ' +
+    'Do not use this feature to evade Telegram limits. Use it at your own risk and keep an independent backup.';
+
+export function getEnabledBots(bots) {
+    return (bots || []).filter(bot => bot.enabled !== false);
+}
+
+/**
+ * Pick a stable enabled bot for a chunk. The file key chooses the starting
+ * offset and the chunk index walks the pool, which distributes a multi-chunk
+ * file without making a retry choose a different endpoint.
+ */
+export function selectBotId(bots, routingKey, chunkIndex = 0) {
+    const enabled = getEnabledBots(bots);
+    if (enabled.length === 0) throw new Error('No enabled Telegram bots configured');
+
+    const digest = crypto.createHash('sha256').update(String(routingKey || '')).digest();
+    const offset = digest.readUInt32BE(0) % enabled.length;
+    return enabled[(offset + chunkIndex) % enabled.length].id;
+}
+
+export class TelegramPool {
+    constructor(dataDir, bots) {
+        if (!Array.isArray(bots) || bots.length === 0) {
+            throw new Error('No Telegram bots configured');
+        }
+
+        this.dataDir = dataDir;
+        this.bots = bots;
+        this.botById = new Map(bots.map(bot => [bot.id, bot]));
+        this.clientPromises = new Map();
+    }
+
+    async initialize({ includeDisabled = true } = {}) {
+        const bots = includeDisabled ? this.bots : getEnabledBots(this.bots);
+        await Promise.all(bots.map(bot => this._getClient(bot.id)));
+        return this;
+    }
+
+    selectBotId(routingKey, chunkIndex = 0) {
+        return selectBotId(this.bots, routingKey, chunkIndex);
+    }
+
+    _normalizeBotId(botId) {
+        if (botId && this.botById.has(botId)) return botId;
+        if (!botId && this.botById.has('primary')) return 'primary';
+        if (!botId && this.bots.length === 1) return this.bots[0].id;
+        throw new Error(`Telegram bot ${botId || '(legacy primary)'} is not configured`);
+    }
+
+    async _getClient(botId) {
+        const normalizedId = this._normalizeBotId(botId);
+        if (!this.clientPromises.has(normalizedId)) {
+            const bot = this.botById.get(normalizedId);
+            const promise = (async () => {
+                const client = new TelegramClient(this.dataDir);
+                await client.initialize(bot.botToken, bot.customApiUrl || null);
+                client.setChatId(bot.chatId);
+                return client;
+            })();
+            this.clientPromises.set(normalizedId, promise);
+        }
+        return this.clientPromises.get(normalizedId);
+    }
+
+    async sendFile(filePath, caption = '', options = {}) {
+        const botId = options.botId || this.selectBotId(options.routingKey, options.chunkIndex || 0);
+        const client = await this._getClient(botId);
+        const { botId: _botId, routingKey: _routingKey, chunkIndex: _chunkIndex, ...clientOptions } = options;
+        const result = await client.sendFile(filePath, caption, clientOptions);
+        return { ...result, botId };
+    }
+
+    async downloadFile(fileId, botId = null) {
+        const client = await this._getClient(botId);
+        return client.downloadFile(fileId);
+    }
+
+    async downloadFileToPath(fileId, destPath, botId = null) {
+        const client = await this._getClient(botId);
+        return client.downloadFileToPath(fileId, destPath);
+    }
+
+    async getFile(fileId, botId = null) {
+        const client = await this._getClient(botId);
+        return client.bot.getFile(fileId);
+    }
+
+    async deleteMessage(messageId, botId = null) {
+        const client = await this._getClient(botId);
+        return client.deleteMessage(messageId);
+    }
+}

package/src/utils/branding.js

@@ -14,7 +14,7 @@ export const LOGO = `
 `;
 
 export const TAGLINE = 'Telegram as Storage';
-export const VERSION = '2.4.1';
+export const VERSION = '3.0.0';
 
 /**
  * Print the TAS banner
@@ -22,7 +22,7 @@ export const VERSION = '2.4.1';
 export function printBanner() {
     console.log(chalk.cyan(LOGO));
     console.log(chalk.dim(`  ${TAGLINE} v${VERSION}`));
-    console.log(chalk.dim('  Free • Encrypted • Unlimited\n'));
+    console.log(chalk.dim('  Experimental • Encrypted • Local-first\n'));
 }
 
 /**

package/src/utils/chunker.js

@@ -1,11 +1,12 @@
 /**
  * File chunking utilities for large files
- * Telegram Bot API limit is 50 MB for bot uploads (sendDocument).
- * We use 49 MB to leave room for the 64-byte WAS1 header.
+ * Telegram's hosted Bot API currently returns files through getFile only up
+ * to 20 MB. Keep the full stored document below that read limit so TAS never
+ * uploads a chunk that it cannot later pull, mount, verify, or share.
  * See: https://core.telegram.org/bots/api#senddocument
  */
 
-const MAX_CHUNK_SIZE = 49 * 1024 * 1024; // 49 MB — Telegram Bot API safe limit
+export const MAX_CHUNK_SIZE = 19 * 1024 * 1024; // 19 MiB payload + 64-byte TAS header
 
 export class Chunker {
     /**

package/src/utils/cli-helpers.js

@@ -61,18 +61,32 @@ export function validateConfig(config) {
         return { valid: false, errors };
     }
 
-    // v2: encrypted token, v1: plaintext token
-    const hasToken = config.encryptedBotToken || config.botToken;
-    if (!hasToken) {
-        errors.push('Missing bot token (botToken or encryptedBotToken)');
-    }
+    const bots = getBotEntries(config);
+    if (bots.length === 0) errors.push('Missing bot configuration');
+
+    const seenIds = new Set();
+    for (const bot of bots) {
+        if (!bot.id || !/^[a-z0-9][a-z0-9_-]{0,31}$/i.test(bot.id)) {
+            errors.push(`Invalid bot id: ${bot.id || '(missing)'}`);
+        } else if (seenIds.has(bot.id)) {
+            errors.push(`Duplicate bot id: ${bot.id}`);
+        }
+        seenIds.add(bot.id);
 
-    if (config.botToken && !config.botToken.includes(':')) {
-        errors.push('Invalid bot token format (should contain :)');
+        if (!bot.encryptedBotToken && !bot.botToken) {
+            errors.push(`Missing token for bot ${bot.id || '(unknown)'}`);
+        }
+        if (bot.botToken && !bot.botToken.includes(':')) {
+            errors.push(`Invalid token format for bot ${bot.id || '(unknown)'}`);
+        }
+        if (bot.chatId === undefined || bot.chatId === null ||
+            (typeof bot.chatId !== 'number' && typeof bot.chatId !== 'string')) {
+            errors.push(`Missing or invalid chatId for bot ${bot.id || '(unknown)'}`);
+        }
     }
 
-    if (!config.chatId || (typeof config.chatId !== 'number' && typeof config.chatId !== 'string')) {
-        errors.push('Missing or invalid chatId');
+    if (bots.length > 0 && !bots.some(bot => bot.enabled !== false)) {
+        errors.push('At least one bot must be enabled');
     }
 
     if (!config.passwordHash || typeof config.passwordHash !== 'string') {
@@ -85,6 +99,35 @@ export function validateConfig(config) {
     };
 }
 
+/**
+ * Return normalized raw bot entries. v1/v2 configs are represented as one
+ * stable `primary` bot so existing vaults require no migration to keep working.
+ */
+export function getBotEntries(config) {
+    if (!config) return [];
+    if (Array.isArray(config.bots)) {
+        return config.bots.map((bot, index) => ({
+            ...bot,
+            id: bot.id || (index === 0 ? 'primary' : `bot-${index + 1}`),
+            enabled: bot.enabled !== false
+        }));
+    }
+
+    if (config.encryptedBotToken || config.botToken) {
+        return [{
+            id: 'primary',
+            encryptedBotToken: config.encryptedBotToken,
+            botToken: config.botToken,
+            chatId: config.chatId,
+            username: config.username,
+            enabled: true,
+            createdAt: config.createdAt
+        }];
+    }
+
+    return [];
+}
+
 /**
  * Decrypt bot token from config using password
  * Supports both v1 (plaintext) and v2 (encrypted) configs
@@ -108,6 +151,20 @@ export function decryptBotToken(config, password) {
     throw new Error('No bot token found in config');
 }
 
+/** Decrypt one normalized bot entry. */
+export function decryptBotEntry(bot, password) {
+    return {
+        ...bot,
+        botToken: decryptBotToken(bot, password)
+    };
+}
+
+/** Encrypt a bot token with the vault password. */
+export function encryptBotToken(token, password) {
+    const encryptor = new Encryptor(password);
+    return encryptor.encrypt(Buffer.from(token, 'utf-8')).toString('base64');
+}
+
 /**
  * Load and validate config
  * @param {string} dataDir - Data directory path
@@ -176,8 +233,31 @@ export async function getAndVerifyPassword(passwordOption, dataDir) {
  * @returns {Object} - Config with decrypted botToken
  */
 export function resolveConfig(config, password) {
+    // Reuse one derived key across the pool; deriving PBKDF2 separately for
+    // every bot made startup scale linearly with the number of configured bots.
+    const encryptor = new Encryptor(password);
+    const bots = getBotEntries(config).map(bot => ({
+        ...bot,
+        botToken: bot.botToken || encryptor.decrypt(Buffer.from(bot.encryptedBotToken, 'base64')).toString('utf-8')
+    }));
+    const primary = bots.find(bot => bot.id === 'primary') || bots[0];
+
     return {
         ...config,
-        botToken: decryptBotToken(config, password)
+        bots,
+        // Keep these aliases for third-party callers that still consume the
+        // v1/v2 shape. New code routes through `bots` and persists bot IDs.
+        botToken: primary.botToken,
+        chatId: primary.chatId,
+        username: primary.username
     };
 }
+
+/** Write config atomically enough for this local CLI and restore mode 0600. */
+export function saveConfig(dataDir, config) {
+    const configPath = path.join(dataDir, 'config.json');
+    const tempPath = `${configPath}.tmp`;
+    fs.writeFileSync(tempPath, JSON.stringify(config, null, 2), { mode: 0o600 });
+    fs.renameSync(tempPath, configPath);
+    try { fs.chmodSync(configPath, 0o600); } catch { /* ignore on Windows */ }
+}

package/src/utils/download-stream.js

@@ -13,8 +13,8 @@ import { parseHeader, HEADER_SIZE } from './chunker.js';
  * Create the download pipeline streams for a file stored in Telegram.
  *
  * @param {object} options
- * @param {object} options.client     – TelegramClient instance (initialized, with chatId set)
- * @param {Array}  options.chunks     – Chunk records from DB, each with { chunk_index, file_telegram_id, size }
+ * @param {object} options.client     – TelegramPool (or compatible single client)
+ * @param {Array}  options.chunks     – Chunk records with { chunk_index, file_telegram_id, bot_id, size }
  * @param {object} options.encryptor  – Encryptor instance
  * @param {object} options.compressor – Compressor instance
  * @param {function} [options.onChunkDownloaded] – Optional callback({ chunkIndex, totalChunks, bytesDownloaded, totalBytes })
@@ -29,7 +29,10 @@ export async function createDownloadPipeline({ client, chunks, encryptor, compre
     const sortedChunks = [...chunks].sort((a, b) => a.chunk_index - b.chunk_index);
 
     // Download the first chunk to inspect the header
-    const firstChunkData = await client.downloadFile(sortedChunks[0].file_telegram_id);
+    const firstChunkData = await client.downloadFile(
+        sortedChunks[0].file_telegram_id,
+        sortedChunks[0].bot_id || null
+    );
     const header = parseHeader(firstChunkData);
 
     const decryptStream = encryptor.getDecryptStream();
@@ -53,7 +56,10 @@ export async function createDownloadPipeline({ client, chunks, encryptor, compre
                     data = preloadedFirst;
                     preloadedFirst = null;
                 } else {
-                    data = await client.downloadFile(sortedChunks[currentIndex].file_telegram_id);
+                    data = await client.downloadFile(
+                        sortedChunks[currentIndex].file_telegram_id,
+                        sortedChunks[currentIndex].bot_id || null
+                    );
                 }
 
                 bytesDownloaded += data.length;

package/src/utils/logical-path.js

@@ -0,0 +1,44 @@
+/** Normalize a TAS logical path to portable POSIX form. */
+export function normalizeLogicalPath(value, { allowRoot = false } = {}) {
+    if (typeof value !== 'string' || value.includes('\0')) {
+        throw new Error('Invalid logical path');
+    }
+
+    const portable = value.replace(/\\/g, '/').replace(/^\/+/, '');
+    const normalized = portable === '' ? '' : portable.split('/').filter(Boolean).join('/');
+    const parts = normalized.split('/').filter(Boolean);
+    if (parts.some(part => part === '.' || part === '..')) {
+        throw new Error('Logical paths cannot contain . or .. segments');
+    }
+    if (!allowRoot && normalized === '') throw new Error('Logical path cannot be empty');
+    return normalized;
+}
+
+export function parentLogicalPath(value) {
+    const normalized = normalizeLogicalPath(value);
+    const index = normalized.lastIndexOf('/');
+    return index < 0 ? '' : normalized.slice(0, index);
+}
+
+/** Return only immediate children for a virtual directory. */
+export function listLogicalChildren(paths, directory = '') {
+    const dir = normalizeLogicalPath(directory, { allowRoot: true });
+    const prefix = dir ? `${dir}/` : '';
+    const children = new Set();
+
+    for (const value of paths) {
+        const logical = normalizeLogicalPath(value);
+        if (!logical.startsWith(prefix)) continue;
+        const remainder = logical.slice(prefix.length);
+        if (!remainder) continue;
+        children.add(remainder.split('/')[0]);
+    }
+    return [...children].sort((a, b) => a.localeCompare(b));
+}
+
+export function isImplicitDirectory(paths, directory) {
+    const dir = normalizeLogicalPath(directory, { allowRoot: true });
+    if (dir === '') return true;
+    const prefix = `${dir}/`;
+    return paths.some(value => normalizeLogicalPath(value).startsWith(prefix));
+}