@ssebastien/tcmd 0.1.4 → 0.1.7

package/src/js/tcmd/core/watch.js

@@ -0,0 +1,153 @@
+// Project: TinyCommand
+// Author:  Sebastien Pierre
+// License: BSD
+// Created: 2026-10-31
+
+// Module: tcmd/core/watch
+// Change notification for a directory listing. A `Directory` watches the
+// displayed path so listings written by other programs appear without a
+// manual reload. The adapter's native `watch(path, onChange)` is preferred —
+// the Node/Bun adapter maps it to `fs.watch`, so events are immediate. An
+// adapter without it (OPFS, the HTTP API, the desktop RPC bridge) falls back
+// to polling and comparing a listing signature, so the behaviour is the same
+// with a few seconds of latency.
+//
+// Watchers are intentionally owned by the directory rather than the views:
+// every pane has one, and a path change re-arms it (see `core/directory`).
+
+// Constant: DEFAULT_DELAY
+// Debounce for native events, which arrive in bursts (a copy emits a change
+// per entry) and would otherwise trigger one read per event.
+const DEFAULT_DELAY = 180
+
+// Constant: DEFAULT_INTERVAL
+// Polling cadence for adapters without a native watcher. Long enough not to
+// hammer a remote API, short enough that changes feel automatic.
+const DEFAULT_INTERVAL = 3000
+
+// Function: listingSignature
+// A cheap order-independent fingerprint of a listing: names, sizes, mtimes
+// and modes. Polling compares it to decide whether the directory really
+// changed, so an unchanged listing never publishes a new entries array.
+function listingSignature(entries) {
+	return (entries ?? [])
+		.map(
+			(entry) =>
+				`${entry?.name ?? ""}\u0000${entry?.size ?? 0}\u0000${entry?.mtimeMs ?? 0}\u0000${entry?.mode ?? 0}`,
+		)
+		.sort()
+		.join("\u0001")
+}
+
+// Function: createPathWatcher
+// Watches `path` through the adapter's `watch` when it has one, or by polling
+// `readDir`. Calls `onChange` when the listing may have changed. Returns a
+// `stop()` that closes the native watcher or clears the poll timer; safe to
+// call more than once.
+//
+// `watch` may return its stop synchronously (Node's adapter) or asynchronously
+// (the desktop adapter, whose watch lives behind an RPC round-trip). Only a
+// failed or unavailable native watch starts polling, so a resolved watch never
+// pays for both.
+//
+// Options:
+// - `delay`: native-event debounce in milliseconds (default 180).
+// - `interval`: fallback polling period in milliseconds (default 3000).
+//
+// Example:
+// ```javascript
+// const stop = createPathWatcher(fs, "/home", () => dir.refresh())
+// ```
+function createPathWatcher(fs, path, onChange, options = {}) {
+	const delay = options.delay ?? DEFAULT_DELAY
+	const interval = options.interval ?? DEFAULT_INTERVAL
+	let stopped = false
+	let debounceTimer = null
+	let pollTimer = null
+	let stopNative = null
+
+	const notify = () => {
+		if (stopped) return
+		onChange?.()
+	}
+
+	const startPolling = () => {
+		if (stopped || pollTimer || typeof fs?.readDir !== "function") return
+		let previous = null
+		const poll = async () => {
+			if (stopped) return
+			let signature
+			try {
+				signature = listingSignature(await fs.readDir(path))
+			} catch (error) {
+				// A vanishing directory is a change too: the next read reports
+				// it to the user instead of leaving a stale listing forever.
+				signature = `error:${error?.code ?? error?.message ?? error}`
+			}
+			if (stopped) return
+			if (previous !== null && signature !== previous) notify()
+			previous = signature
+			pollTimer = setTimeout(() => void poll(), interval)
+			pollTimer?.unref?.()
+		}
+		pollTimer = setTimeout(() => void poll(), interval)
+		pollTimer?.unref?.()
+	}
+
+	const useNativeWatch = (watched) => {
+		if (stopped) {
+			watched?.()
+			return
+		}
+		if (typeof watched === "function") {
+			stopNative = watched
+			return
+		}
+		startPolling()
+	}
+
+	if (typeof fs?.watch === "function") {
+		let watching = null
+		try {
+			watching = fs.watch(path, () => {
+				if (stopped) return
+				if (debounceTimer) clearTimeout(debounceTimer)
+				debounceTimer = setTimeout(() => {
+					debounceTimer = null
+					notify()
+				}, delay)
+				debounceTimer?.unref?.()
+			})
+		} catch (error) {
+			watching = null
+		}
+		// An async adapter (the desktop RPC bridge) resolves to its stop; a
+		// null/undefined or rejected result means polling takes over.
+		if (typeof watching?.then === "function") {
+			watching.then(useNativeWatch, () => startPolling())
+		} else {
+			useNativeWatch(watching)
+		}
+	} else {
+		startPolling()
+	}
+
+	return () => {
+		if (stopped) return
+		stopped = true
+		if (debounceTimer) {
+			clearTimeout(debounceTimer)
+			debounceTimer = null
+		}
+		if (pollTimer) {
+			clearTimeout(pollTimer)
+			pollTimer = null
+		}
+		stopNative?.()
+		stopNative = null
+	}
+}
+
+export { createPathWatcher, DEFAULT_DELAY, DEFAULT_INTERVAL, listingSignature }
+
+// EOF

package/src/js/tcmd/desktop/backend/api.js

@@ -0,0 +1,165 @@
+// Project: TinyCommand
+// License: BSD
+// Module: tcmd/desktop/backend/api
+// Named tinyjs RPC methods. The browser receives only the filesystem adapter
+// methods it needs; filesystem and process primitives stay in this backend.
+
+import { encodeBase64 } from "../../core/base64.js"
+import { createDesktopFs, normalizePath } from "./fs.js"
+
+const OUTPUT_LIMIT = 32 * 1024
+const decoder = new TextDecoder()
+
+function requirePath(value, base) {
+	return normalizePath(value, base)
+}
+
+async function readLimited(stream, limit = OUTPUT_LIMIT) {
+	if (!stream) return { text: "", truncated: false }
+	const reader = stream.getReader()
+	const chunks = []
+	let size = 0
+	let truncated = false
+	try {
+		while (true) {
+			const { value, done } = await reader.read()
+			if (done) break
+			if (!value?.length) continue
+			const remaining = limit - size
+			if (remaining > 0) {
+				const chunk = value.subarray(0, remaining)
+				chunks.push(chunk)
+				size += chunk.length
+			}
+			if (value.length > remaining) truncated = true
+		}
+	} finally {
+		reader.releaseLock?.()
+	}
+	const bytes = new Uint8Array(size)
+	let offset = 0
+	for (const chunk of chunks) {
+		bytes.set(chunk, offset)
+		offset += chunk.length
+	}
+	return { text: decoder.decode(bytes), truncated }
+}
+
+function createDesktopBackend({ runtime } = {}) {
+	if (!runtime) throw new TypeError("txiki.js runtime is required")
+	let filesystem = null
+	let pendingOpenFiles = []
+	// Native directory watchers, keyed by window and the frontend's watcher id.
+	// The main window owns the whole workspace; a page reload resets its set
+	// (`fsWatchReset`) so old watchers never outlive the page that asked.
+	const watchers = new Map()
+	const watchKey = (meta, id) => `${meta?.window ?? "main"}\u0000${id}`
+	const watchId = (id) => {
+		if (typeof id !== "string" || !id) throw new TypeError("watch id must be a non-empty string")
+		return id
+	}
+	const fs = () => (filesystem ??= createDesktopFs({ runtime }))
+	const fsInfo = () => ({
+		home: fs().home(),
+		cwd: fs().cwd(),
+		root: fs().root(),
+		host: runtime.hostName ?? "",
+		platform: runtime.env?.OS === "Windows_NT" ? "windows" : "posix",
+	})
+
+	const api = {
+		fsInfo,
+		fsReadDir: ({ path }) => fs().readDir(path),
+		fsStat: ({ path }) => fs().stat(path),
+		fsRealpath: ({ path }) => fs().realpath(path),
+		// Directory watching: the frontend keeps a watcher id per pane and
+		// receives `fs-change` pushes over one shared channel.
+		fsWatch: ({ path, id }, app, meta) => {
+			const key = watchKey(meta, watchId(id))
+			watchers.get(key)?.close()
+			const watcher = runtime.watch(requirePath(path, runtime.cwd), () => app.push("fs-change", { id }))
+			watchers.set(key, watcher)
+			return true
+		},
+		fsUnwatch: ({ id }, _app, meta) => {
+			const key = watchKey(meta, watchId(id))
+			watchers.get(key)?.close()
+			watchers.delete(key)
+			return true
+		},
+		fsWatchReset: (_params, _app, meta) => {
+			const prefix = watchKey(meta, "")
+			for (const [key, watcher] of watchers) {
+				if (!key.startsWith(prefix)) continue
+				watcher.close()
+				watchers.delete(key)
+			}
+			return true
+		},
+		fsReadTextHead: ({ path, maxBytes }) => fs().readTextHead(path, maxBytes),
+		fsReadBytes: async ({ path, maxBytes }) => ({
+			base64: encodeBase64(await fs().readBytes(path, maxBytes)),
+		}),
+		fsDu: ({ path }) => fs().du(path),
+		fsDisk: ({ path }) => fs().disk(path),
+		fsCopy: ({ from, to }) => fs().copy(from, to),
+		fsMove: ({ from, to }) => fs().move(from, to),
+		fsHardlink: ({ from, to }) => fs().hardlink(from, to),
+		fsSymlink: ({ target, link }) => fs().symlink(target, link),
+		fsChmod: ({ path, mode }) => fs().chmod(path, mode),
+		fsChown: ({ path, owner }) => fs().chown(path, owner),
+		fsUnlink: ({ path }) => fs().unlink(path),
+		fsTrash: ({ paths }) => fs().trash(paths),
+		fsTrashList: () => fs().trashList(),
+		fsRestore: ({ paths }) => fs().restore(paths),
+		fsTakeOpenFiles: () => pendingOpenFiles.splice(0),
+		fsErase: ({ paths }) => fs().erase(paths),
+		fsTouch: ({ path }) => fs().touch(path),
+		fsMkdir: ({ path }) => fs().mkdir(path),
+		hostOpen: async ({ path }, app) => app.shell.open(requirePath(path, runtime.cwd)),
+		hostEdit: async ({ path }, app) => app.shell.open(requirePath(path, runtime.cwd)),
+		hostRun: async ({ command, cwd }, app) => {
+			if (typeof command !== "string" || !command.trim()) throw new TypeError("command must be non-empty text")
+			if (command.length > 65536 || command.includes("\0")) throw new Error("command is too long or contains NUL")
+			const directory = requirePath(cwd || fs().cwd(), runtime.cwd)
+			const stats = await fs().stat(directory)
+			if (!stats?.isDir) throw new Error(`not a directory: ${directory}`)
+			const shell = runtime.env?.SHELL || "/bin/sh"
+			const child = runtime.spawn([shell, "-c", command], {
+				cwd: directory,
+				stdin: "ignore",
+				stdout: "pipe",
+				stderr: "pipe",
+			})
+			const [stdout, stderr, status] = await Promise.all([
+				readLimited(child.stdout),
+				readLimited(child.stderr),
+				child.wait(),
+			])
+			return {
+				stdout: stdout.text,
+				stderr: stderr.text,
+				exitCode: status.exit_status,
+				signal: status.term_signal,
+				truncated: stdout.truncated || stderr.truncated,
+			}
+		},
+	}
+
+	return {
+		api,
+		// tinyjs invokes this for folders passed on the command line, associated
+		// folders, and files dropped onto the app. The frontend applies them once
+		// its session is ready.
+		onOpenFiles(paths, app) {
+			if (Array.isArray(paths) && paths.length) {
+				pendingOpenFiles.push(...paths.filter((path) => typeof path === "string"))
+				app.push("open-files", true)
+			}
+		},
+	}
+}
+
+export { createDesktopBackend, readLimited }
+
+// EOF