@ssebastien/tcmd 0.1.3 → 0.1.7

package/src/js/tcmd/core/concurrency.js

@@ -0,0 +1,59 @@
+// Project: TinyCommand
+// Author:  Sebastien Pierre
+// License: BSD
+// Created: 2026-10-18
+
+// Module: tcmd/core/concurrency
+// Bounded async helpers. Both filesystem adapters list a directory by statting
+// every entry; doing that one await at a time starves the host's threadpool, so
+// each issues a bounded window of requests concurrently instead. `mapLimit`
+// bounds one pass; `createLimiter` bounds a recursive walk, where the fan-out
+// at each level would otherwise multiply. Pure, so the browser bundle can share
+// them with the Node adapter.
+
+// Function: mapLimit
+// `map` over `items` with at most `limit` mappers in flight, preserving order.
+async function mapLimit(items, limit, mapper) {
+	const result = new Array(items.length)
+	let next = 0
+	const worker = async () => {
+		while (next < items.length) {
+			const index = next++
+			result[index] = await mapper(items[index], index)
+		}
+	}
+	const workers = []
+	for (let i = 0; i < Math.min(limit, items.length); i++) workers.push(worker())
+	await Promise.all(workers)
+	return result
+}
+
+// Function: createLimiter
+// Wraps calls so at most `limit` run concurrently, queueing the rest. Unlike
+// `mapLimit`, every call shares one global slot, so a recursive walk can bound
+// its total in-flight work rather than multiplying the limit per level.
+function createLimiter(limit) {
+	let active = 0
+	const queue = []
+	const pump = () => {
+		if (active >= limit || queue.length === 0) return
+		active += 1
+		const { fn, resolve, reject } = queue.shift()
+		Promise.resolve()
+			.then(fn)
+			.then(resolve, reject)
+			.finally(() => {
+				active -= 1
+				pump()
+			})
+	}
+	return (fn) =>
+		new Promise((resolve, reject) => {
+			queue.push({ fn, resolve, reject })
+			pump()
+		})
+}
+
+export { createLimiter, mapLimit }
+
+// EOF

package/src/js/tcmd/core/decompress.js

@@ -0,0 +1,117 @@
+// Project: TinyCommand
+// Author:  Sebastien Pierre
+// License: BSD
+// Created: 2026-10-20
+
+// Module: tcmd/core/decompress
+// Head decompression for compressed previews. `core/session` reads a bounded
+// run of the file's raw bytes through the filesystem adapter and hands it here;
+// the result is the leading decompressed text (never more than the requested
+// budget), which the preview treats exactly like a plain text head.
+//
+// Gzip uses the platform's `DecompressionStream` (Bun and every browser ship
+// it). Bzip2 has no such primitive, so the vendored decoder does the work; its
+// output is a binary string that is decoded as UTF-8 here.
+
+import { bzip2 } from "../vendor/bzip2.js"
+import { PREVIEW_BYTES } from "./preview.js"
+
+// Constant: BZIP2_BLOCK_BYTES
+// A bzip2 stream decodes one block at a time and cannot emit anything until
+// the whole block is in hand. Block size 9 holds at most 900 kB, so reading
+// this much compressed data always covers the first block (plus its header).
+const BZIP2_BLOCK_BYTES = 1024 * 1024
+
+// Function: compressedBytes
+// How many raw bytes the adapter should read for a compression format: gzip
+// can be streamed and a preview-sized run is plenty; bzip2 needs its first
+// whole block.
+function compressedBytes(compression) {
+	return compression === "bzip2" ? BZIP2_BLOCK_BYTES : PREVIEW_BYTES
+}
+
+// Function: decompressHead
+// Leading `maxBytes` of decompressed text for `compression` ("gzip" or
+// "bzip2"). Throws on a corrupt or unsupported stream; callers fall back to a
+// metadata card.
+async function decompressHead(bytes, compression, maxBytes = PREVIEW_BYTES) {
+	if (compression === "gzip") return gunzipHead(bytes, maxBytes)
+	if (compression === "bzip2") return bunzip2Head(bytes, maxBytes)
+	throw new Error(`unsupported compression: ${compression}`)
+}
+
+// Function: gunzipHead
+// Streams gzip members and stops at `maxBytes` of output. A truncated head is
+// fine: the reader is cancelled once the budget is spent or the input ends.
+async function gunzipHead(bytes, maxBytes) {
+	const stream = new Blob([bytes]).stream().pipeThrough(new DecompressionStream("gzip"))
+	const reader = stream.getReader()
+	const chunks = []
+	let length = 0
+	try {
+		while (length < maxBytes) {
+			const { value, done } = await reader.read()
+			if (done) break
+			if (!value?.length) continue
+			chunks.push(value)
+			length += value.length
+		}
+	} finally {
+		await reader.cancel().catch(() => {})
+	}
+	return decodeBytes(chunks, maxBytes)
+}
+
+// Function: bunzip2Head
+// Decodes blocks until `maxBytes` of output or the stream terminator. The
+// decoder yields one byte per char code, so the collected string is converted
+// back to bytes before UTF-8 decoding.
+function bunzip2Head(bytes, maxBytes) {
+	let chunks
+	try {
+		const bits = bzip2.array(bytes)
+		const size = bzip2.header(bits)
+		chunks = []
+		let length = 0
+		while (length < maxBytes) {
+			const chunk = bzip2.decompress(bits, size, maxBytes - length)
+			if (chunk === -1) break
+			chunks.push(chunk)
+			length += chunk.length
+		}
+	} catch (error) {
+		// The vendored decoder throws bare strings.
+		throw error instanceof Error ? error : new Error(`${error}`)
+	}
+	return decodeBytes(chunks.map(byteString), maxBytes)
+}
+
+// Function: byteString
+// The vendored decoder's char codes are bytes, not text.
+function byteString(text) {
+	const bytes = new Uint8Array(text.length)
+	for (let i = 0; i < text.length; i++) bytes[i] = text.charCodeAt(i) & 0xff
+	return bytes
+}
+
+// Function: decodeBytes
+// Concatenates the chunks (bounded to `maxBytes`) and decodes them as UTF-8.
+function decodeBytes(chunks, maxBytes) {
+	const total = Math.min(
+		chunks.reduce((size, chunk) => size + chunk.length, 0),
+		maxBytes,
+	)
+	const bytes = new Uint8Array(total)
+	let offset = 0
+	for (const chunk of chunks) {
+		if (offset >= total) break
+		const take = Math.min(chunk.length, total - offset)
+		bytes.set(chunk.subarray(0, take), offset)
+		offset += take
+	}
+	return new TextDecoder().decode(bytes)
+}
+
+export { compressedBytes, decompressHead }
+
+// EOF

package/src/js/tcmd/core/directory.js

@@ -9,39 +9,34 @@
 // figures, the selection buffer and the navigation history (back/forward).
 // A pane owns exactly one directory — the
 // former multi-tab model is gone — and the pane's cells proxy it directly.
+//
+// Reads commit atomically: the displayed directory (path, listing, filter,
+// marks, cursor) is replaced in one reactive batch once its replacement is
+// ready, and only the latest read may publish (see `read`). Listings carry
+// their stat details, so the cursor entry needs no separate enrichment pass.
 
-import { cell, derived, effect } from "select/state/cells"
+import { batch, cell, derived } from "select/state/cells"
 import { viewEntries } from "./entries.js"
-import { clampCursor, currentEntry, toggleMark } from "./selection.js"
+import { createHistory } from "./history.js"
+import { clampCursor, currentEntry, indexOfPath, toggleMark } from "./selection.js"
 import { SEP, parent as parentPath, split, prefix } from "./path.js"
-
-// Function: enrichEntry
-// Merges `stat` details (ctime, mode, uid, gid) the listing may not carry.
-async function enrichEntry(fs, entry) {
-	if (!entry) return null
-	const stats = await fs.stat(entry.path).catch(() => null)
-	if (!stats) return entry
-	return {
-		...entry,
-		size: entry.isDir ? 0 : (stats.size ?? entry.size),
-		mtimeMs: stats.mtimeMs ?? entry.mtimeMs,
-		ctimeMs: stats.ctimeMs ?? entry.ctimeMs,
-		mode: stats.mode ?? entry.mode,
-		uid: stats.uid ?? entry.uid,
-		gid: stats.gid ?? entry.gid,
-	}
-}
+import { createPathWatcher } from "./watch.js"
 
 // Function: createDirectory
 // Creates the directory state for one pane, bound to a filesystem adapter.
 //
+// Options:
+// - `watch`: true (default) auto-refreshes when the displayed directory
+//   changes; false disables it; an object forwards `{ delay, interval }` to
+//   `core/watch` (tests use a short delay).
+//
 // Example:
 // ```javascript
 // const dir = createDirectory({ fs: createNodeFs(), path: "/home" })
 // await dir.refresh()
 // dir.entries.value // sorted, filtered FileEntry[]
 // ```
-function createDirectory({ fs, path: initialPath }) {
+function createDirectory({ fs, path: initialPath, context: initialContext, watch = true }) {
 	const dir = { fs }
 	dir.path = cell(initialPath)
 	dir.rawEntries = cell([])
@@ -54,105 +49,231 @@ function createDirectory({ fs, path: initialPath }) {
 	)
 	dir.cursor = cell(0)
 	dir.disk = cell(null)
-	// Stat details (ctime, mode, uid, gid) for the entry under the cursor,
-	// fetched lazily: listings only carry size/mtime, so the pane detail line
-	// re-stats the selected path when the cursor moves (cached by path).
-	dir.cursorStat = cell(null)
-	let cursorStatPath = null
 	// Selection buffer for this directory (the pane's marked paths).
 	dir.marked = cell(new Set())
-	// Navigation history: visited paths with the current one at
-	// `history.index`, so back/forward walk the stack like a browser.
-	dir.history = { stack: [initialPath], index: 0 }
+	// An opaque per-entry value the owner captures into the history and gets
+	// back on restore. The session uses it to restore the focused column; the
+	// directory itself never inspects it.
+	let context = initialContext
+	const contextGet = () => context?.get?.()
+	const contextSet = (value) => context?.set?.(value)
+	// Function: snapshot
+	// The directory's restorable view state: path, filter, cursor, marks and
+	// the owner's context.
+	const snapshot = () => ({
+		path: dir.path.value,
+		filter: dir.filter.value,
+		cursor: dir.cursor.value,
+		marks: new Set(dir.marked.value),
+		context: contextGet(),
+	})
+	// Navigation history: full view snapshots with the current one at
+	// `history.index`, so back/forward restore position, selection and filter
+	// like a browser.
+	dir.history = createHistory(snapshot())
+	// Cursor memory: the last cursor position per path, so re-entering a
+	// directory (a fresh `open`, not a history step) lands on the entry that
+	// was last selected there.
+	const cursorMemory = new Map()
+	let readToken = 0
+	// Auto-refresh: one watcher on the displayed path. It is re-armed after a
+	// move commits and released on dispose. A change notification during a
+	// *move* is ignored — the read in flight is already producing the next
+	// listing, and refreshing the path being left would race its token. During
+	// a plain refresh a notification may supersede it: the newer read carries
+	// the newest change, so no event is ever lost to a slow listing.
+	const watchOptions = watch === false ? null : watch === true || watch == null ? {} : watch
+	// Whether this directory currently watches its path. The session pauses
+	// columns the view does not show, so a hidden pane does not keep polling
+	// the filesystem (or hold a desktop RPC watcher) for nothing.
+	dir.autoRefresh = cell(Boolean(watchOptions))
+	let watchedPath = null
+	let stopWatcher = null
+	let moving = false
+	const stopWatching = () => {
+		stopWatcher?.()
+		stopWatcher = null
+		watchedPath = null
+	}
+	const watchCurrentPath = () => {
+		if (!watchOptions || !dir.autoRefresh.value || watchedPath === dir.path.value) return
+		stopWatching()
+		const path = dir.path.value
+		watchedPath = path
+		stopWatcher = createPathWatcher(
+			fs,
+			path,
+			() => {
+				if (moving || watchedPath !== dir.path.value) return
+				void dir.refresh()
+			},
+			watchOptions,
+		)
+	}
 
-	// A changing filter re-ranks the listing: snap the cursor back to the top
-	// match. Disposed with the directory (see `dispose`).
-	const stopFilterWatch = effect([dir.filter], () => dir.cursor.set(0))
+	// Function: setContext
+	// Replaces the owner context captured into history entries.
+	dir.setContext = (next) => {
+		context = next
+	}
 
-	// Re-stat the cursor entry on movement; cache by path so a re-render that
-	// does not move the cursor does not hit the filesystem again.
-	const stopCursorWatch = effect([dir.entries, dir.cursor], () => {
-		const entry = currentEntry(dir.entries.value, dir.cursor.value)
-		if (!entry || entry.path === cursorStatPath) return
-		cursorStatPath = entry.path
-		dir.cursorStat.set(entry)
-		void enrichEntry(fs, entry).then((enriched) => {
-			if (cursorStatPath === entry.path) dir.cursorStat.set(enriched)
+	// Function: read
+	// Reads `path` and, unless a newer read supersedes it, commits the listing
+	// as one atomic update: the displayed directory stays intact until its
+	// replacement is ready, and disk figures never delay the listing.
+	//
+	// Options:
+	// - `move`: move to `path` (reset filter and marks, remember the cursor
+	//   for re-entry). Without it, `read` re-reads the displayed directory in
+	//   place, preserving filter, marks and cursor (`refresh`).
+	// - `record`: also record the move in the history (a navigation). Mirror
+	//   columns move without recording.
+	// - `cursorPath`: land the cursor on that entry when the listing has it.
+	// - `restore`: a history snapshot to restore instead of a fresh move.
+	const read = async (
+		path,
+		{ move = false, record = false, cursorPath = null, restore = null } = {},
+	) => {
+		const token = ++readToken
+		const isMove = move || Boolean(restore)
+		// A refresh keeps the same entry selected when entries are inserted or
+		// removed above it; the raw cursor index alone would drift, which
+		// matters once refreshes happen behind the user's back.
+		const keepPath = !isMove ? (dir.currentEntry()?.path ?? null) : null
+		if (isMove) moving = true
+		batch(() => {
+			dir.loading.set(true)
+			dir.error.set(null)
 		})
-	})
-
-	// Function: refresh
-	// Re-reads the directory at `dir.path`, updating `rawEntries` and clamping
-	// the cursor. Sets `loading` while in flight; failures land in `error`.
-	dir.refresh = async () => {
-		dir.loading.set(true)
-		dir.error.set(null)
 		try {
-			dir.rawEntries.set(await fs.readDir(dir.path.value))
-			dir.cursor.set(clampCursor(dir.cursor.value, dir.entries.value.length))
-			dir.disk.set(await fs.disk(dir.path.value))
+			const raw = await fs.readDir(path)
+			if (token !== readToken) return
+			const filter = restore ? restore.filter : isMove ? "" : dir.filter.value
+			const entries = viewEntries(raw, filter, dir.sort.value)
+			let cursor
+			if (restore) {
+				cursor = clampCursor(restore.cursor, entries.length)
+			} else {
+				const remembered = isMove && path !== dir.path.value
+					? (cursorMemory.get(path) ?? 0)
+					: dir.cursor.value
+				const kept = keepPath ? indexOfPath(entries, keepPath) : -1
+				const selected = cursorPath ? indexOfPath(entries, cursorPath) : -1
+				cursor = clampCursor(kept >= 0 ? kept : selected >= 0 ? selected : remembered, entries.length)
+			}
+			// A move that rewrites the filter sets the cursor it computed; no
+			// watcher intervenes (the filter cell is written directly, not
+			// through `setFilter`).
+			batch(() => {
+				if (restore) {
+					dir.path.set(path)
+					dir.filter.set(restore.filter)
+					dir.marked.set(new Set(restore.marks))
+					dir.disk.set(null)
+					contextSet(restore.context)
+				} else if (isMove) {
+					cursorMemory.set(dir.path.value, dir.cursor.value)
+					// Capture the view being left before overwriting it, but
+					// only for recorded moves: mirror columns keep no history.
+					if (record) dir.history.replace(snapshot())
+					dir.path.set(path)
+					dir.filter.set("")
+					dir.marked.set(new Set())
+					dir.disk.set(null)
+				}
+				dir.rawEntries.set(raw)
+				dir.cursor.set(cursor)
+				dir.loading.set(false)
+			})
+			watchCurrentPath()
+			if (record) {
+				const entry = { path, filter: "", cursor, marks: new Set(), context: contextGet() }
+				// Re-navigating to the current path updates the entry instead of
+				// duplicating it.
+				if (dir.history.current()?.path === path) dir.history.replace(entry)
+				else dir.history.push(entry)
+			}
+			const disk = await fs.disk(path)
+			if (token === readToken) dir.disk.set(disk)
 		} catch (error) {
-			dir.error.set(`${error?.message ?? error}`)
+			if (token === readToken) dir.error.set(`${error?.message ?? error}`)
 		} finally {
-			dir.loading.set(false)
+			if (token === readToken) {
+				moving = false
+				dir.loading.set(false)
+			}
 		}
 	}
 
-	// Function: apply
-	// The actual move to `path`: sets the path, resets filter, marks and
-	// cursor, then refreshes. History-neutral — navigate/back/forward record
-	// their own steps around it.
-	const apply = async (path) => {
-		dir.path.set(path)
-		dir.filter.set("")
-		dir.marked.set(new Set())
-		dir.cursor.set(0)
-		await dir.refresh()
-	}
+	// Function: refresh
+	// Re-reads the displayed directory, preserving filter, marks and cursor.
+	dir.refresh = () => read(dir.path.value)
 
-	// Function: navigate
-	// Moves the directory to `path` (resetting filter, marks and cursor),
-	// records the step in the history and refreshes. Re-navigating to the
-	// current path does not duplicate the entry.
-	dir.navigate = async (path) => {
-		const history = dir.history
-		if (history.stack[history.index] !== path) {
-			// A new navigation truncates the forward branch, like a browser.
-			history.stack.length = history.index + 1
-			history.stack.push(path)
-			history.index = history.stack.length - 1
+	// Function: setAutoRefresh
+	// Pauses or resumes the path watcher. Resuming re-reads the listing: it
+	// may have changed while the column was hidden and unwatched. A no-op for
+	// a directory created with `watch: false`, and while a move is in flight
+	// (that read already produces the next listing and re-arms the watcher).
+	dir.setAutoRefresh = (enabled) => {
+		if (!watchOptions) return
+		const next = enabled !== false
+		if (dir.autoRefresh.value === next) return
+		dir.autoRefresh.set(next)
+		if (!next) {
+			stopWatching()
+			return
+		}
+		if (!moving) {
+			watchCurrentPath()
+			void dir.refresh()
 		}
-		await apply(path)
 	}
 
+	// Function: navigate
+	// Moves the directory to `path` (resetting filter and marks, restoring the
+	// cursor remembered for `path`), records the step in the history and reads
+	// the listing. Re-navigating to the current path does not duplicate the
+	// entry. `record: false` mirrors without touching the history (the
+	// explorer's parent and inspector columns).
+	dir.navigate = (path, { cursorPath = null, record = true } = {}) =>
+		read(path, { move: true, record, cursorPath })
+
 	// Function: back
-	// Steps one entry back in the navigation history; no-op at its start.
+	// Restores the previous history entry — path, filter, cursor and marks —
+	// and reads it; no-op at the start of the history.
 	dir.back = async () => {
-		const history = dir.history
-		if (history.index <= 0) return
-		history.index -= 1
-		await apply(history.stack[history.index])
+		const entry = dir.history.back()
+		if (entry) await read(entry.path, { restore: entry })
 	}
 
 	// Function: forward
-	// Steps one entry forward in the navigation history; no-op at its end.
+	// Restores the next history entry; no-op at the end of the history.
 	dir.forward = async () => {
-		const history = dir.history
-		if (history.index >= history.stack.length - 1) return
-		history.index += 1
-		await apply(history.stack[history.index])
+		const entry = dir.history.forward()
+		if (entry) await read(entry.path, { restore: entry })
 	}
 
 	// Function: up
-	// Navigates to the parent directory; no-op at the filesystem root.
+	// Navigates to the parent directory, landing the cursor on the entry we
+	// came from — stepping up always returns to the previously selected
+	// element. No-op at the filesystem root.
 	dir.up = async () => {
-		const target = parentPath(dir.path.value)
-		if (target) await dir.navigate(target)
+		const cameFrom = dir.path.value
+		const target = parentPath(cameFrom)
+		if (!target) return
+		await dir.navigate(target, { cursorPath: cameFrom })
+	}
+
+	// Function: setFilter
+	// Sets the fuzzy filter and re-anchors the cursor on the first match.
+	dir.setFilter = (query) => {
+		dir.filter.set(query)
+		dir.cursor.set(0)
 	}
 
 	// Function: clearFilter
 	// Removes the directory's filter, restoring the full listing.
-	dir.clearFilter = () => dir.filter.set("")
+	dir.clearFilter = () => dir.setFilter("")
 
 	// Function: open
 	// Opens the entry under the cursor: descends into directories.
@@ -182,12 +303,17 @@ function createDirectory({ fs, path: initialPath }) {
 	})
 
 	// Function: dispose
-	// Releases the directory's reactive watchers.
+	// Cancels any in-flight read so a late listing can no longer publish, and
+	// releases the path watcher.
 	dir.dispose = () => {
-		stopFilterWatch()
-		stopCursorWatch()
+		readToken += 1
+		stopWatching()
 	}
 
+	// Start watching the opening directory; a later move re-arms the watcher
+	// on its target (see `read`).
+	watchCurrentPath()
+
 	return dir
 }
 

package/src/js/tcmd/core/format.js

@@ -0,0 +1,36 @@
+// Project: TinyCommand
+// Author:  Sebastien Pierre
+// License: BSD
+// Created: 2026-10-31
+
+// Module: tcmd/core/format
+// Domain-level formatting of byte sizes and filesystem capacity. These live in
+// core, not components, because operations report sizes too (`stat`, `du`,
+// `df`); the component formatters re-export them so every renderer and every
+// operation shares one wording.
+
+// Function: formatSize
+// Human-readable byte size, e.g. "512B", "2.0K", "3.8M".
+function formatSize(bytes) {
+	const value = Number(bytes ?? 0)
+	if (value < 1024) return `${value}B`
+	const units = ["K", "M", "G", "T"]
+	let size = value / 1024
+	let unit = 0
+	while (size >= 1024 && unit < units.length - 1) {
+		size /= 1024
+		unit++
+	}
+	return `${size >= 100 ? Math.round(size) : size.toFixed(1)}${units[unit]}`
+}
+
+// Function: formatDisk
+// Compact free/total disk line, e.g. "12G free of 256G".
+function formatDisk(disk) {
+	if (!disk) return ""
+	return `${formatSize(disk.free)} free of ${formatSize(disk.total)}`
+}
+
+export { formatDisk, formatSize }
+
+// EOF