@ssebastien/tcmd 0.0.0-stage → 0.1.0

package/src/js/tcmd/web/opfs.js

@@ -0,0 +1,282 @@
+// Project: TinyCommand
+// Author:  Sebastien Pierre
+// License: BSD
+// Created: 2026-09-27
+
+// Module: tcmd/web/opfs
+// Origin Private File System adapter for `core/fs`. Implements the adapter
+// interface documented in `core/fs.js` on top of OPFS directory/file handles,
+// mapping POSIX-style tcmd paths ("/home/tester") onto the storage root.
+// Requires a secure context (https or localhost); the root handle is resolved
+// lazily, so importing this module has no browser dependency and tests can
+// inject a fake `root`.
+//
+// Beyond the core interface, `writeText` (create/replace a UTF-8 file,
+// creating parents) backs the demo seeding in `web/main.js`.
+//
+// Trash: OPFS has no system trash, so `trash(paths)` moves entries into a
+// `/.trash` directory at the storage root, where they stay browsable.
+
+import { basename, extname, join, normalize, parent, split } from "../core/path.js"
+
+// Function: createOpfsFs
+// Builds the filesystem adapter. `root` overrides the OPFS root handle (tests);
+// `home` is the directory `home()`/`cwd()` report.
+function createOpfsFs({ root, home = "/home/tester" } = {}) {
+	let rootHandle = root ?? null
+
+	// Function: getRoot
+	// Resolves (once) and returns the OPFS root directory handle.
+	async function getRoot() {
+		if (rootHandle) return rootHandle
+		const storage = globalThis.navigator?.storage
+		if (!storage?.getDirectory) throw new Error("OPFS is not available in this browser")
+		rootHandle = await storage.getDirectory()
+		return rootHandle
+	}
+
+	// Function: resolveDir
+	// Resolves `path` to a directory handle; when `create` is set, missing
+	// directories along the way are created.
+	async function resolveDir(path, { create = false } = {}) {
+		let directory = await getRoot()
+		for (const name of split(path)) {
+			directory = await directory.getDirectoryHandle(name, { create })
+		}
+		return directory
+	}
+
+	// Function: resolveFile
+	// Resolves `path` to a file handle, or null when it is missing or is a
+	// directory.
+	async function resolveFile(path) {
+		const directory = await resolveDir(parent(path) ?? "/")
+		try {
+			return await directory.getFileHandle(basename(path))
+		} catch (error) {
+			if (error?.name === "NotFoundError" || error?.name === "TypeMismatchError") return null
+			throw error
+		}
+	}
+
+	// Function: ensureDir
+	// Creates `path` (and its parents) and returns its directory handle.
+	async function ensureDir(path) {
+		const normalized = normalize(path)
+		const directory = await resolveDir(parent(normalized) ?? "/", { create: true })
+		return directory.getDirectoryHandle(basename(normalized), { create: true })
+	}
+
+	// Function: toEntry
+	// Maps an OPFS handle to the core FileEntry shape.
+	async function toEntry(dirPath, handle) {
+		const path = join(dirPath, handle.name)
+		if (handle.kind === "directory") {
+			return {
+				name: handle.name,
+				path,
+				isDir: true,
+				isSymlink: false,
+				isDevice: false,
+				size: 0,
+				mtimeMs: 0,
+				ctimeMs: 0,
+				mode: 0,
+				uid: null,
+				gid: null,
+				owner: "",
+				ext: null,
+			}
+		}
+		const file = await handle.getFile()
+		return {
+			name: handle.name,
+			path,
+			isDir: false,
+			isSymlink: false,
+			isDevice: false,
+			size: file.size,
+			mtimeMs: file.lastModified,
+			ctimeMs: 0,
+			mode: 0,
+			uid: null,
+			gid: null,
+			owner: "",
+			ext: extname(handle.name),
+		}
+	}
+
+	// Function: stat
+	// Stat info for a file, a directory, or null when `path` does not exist.
+	async function stat(path) {
+		const normalized = normalize(path)
+		const zero = { ctimeMs: 0, mode: 0, uid: null, gid: null, owner: "" }
+		if (normalized === "/") return { isDir: true, isSymlink: false, isDevice: false, size: 0, mtimeMs: 0, ...zero }
+		try {
+			await resolveDir(normalized)
+			return { isDir: true, isSymlink: false, isDevice: false, size: 0, mtimeMs: 0, ...zero }
+		} catch (error) {
+			// Not a directory (missing, or a file sits at this path).
+		}
+		try {
+			const handle = await resolveFile(normalized)
+			if (!handle) return null
+			const file = await handle.getFile()
+			return { isDir: false, isSymlink: false, isDevice: false, size: file.size, mtimeMs: file.lastModified, ...zero }
+		} catch (error) {
+			return null
+		}
+	}
+
+	// Function: readDir
+	// Lists `path` as FileEntry-like rows.
+	async function readDir(path) {
+		const directory = await resolveDir(normalize(path))
+		const entries = []
+		for await (const handle of directory.values()) entries.push(await toEntry(path, handle))
+		return entries
+	}
+
+	// Function: readTextHead
+	// Leading `maxBytes` of a text file, decoded as UTF-8.
+	async function readTextHead(path, maxBytes = 65536) {
+		const handle = await resolveFile(normalize(path))
+		if (!handle) throw notFound(path)
+		const file = await handle.getFile()
+		return file.slice(0, maxBytes).text()
+	}
+
+	// Function: du
+	// Recursive size in bytes; unreadable entries contribute 0.
+	async function du(path) {
+		const stats = await stat(path)
+		if (!stats) return 0
+		if (!stats.isDir) return stats.size
+		let total = 0
+		for (const entry of await readDir(path)) {
+			total += entry.isDir ? await du(entry.path) : entry.size
+		}
+		return total
+	}
+
+	// Function: disk
+	// Storage estimate as `{ free, total }`, or null when the browser does not
+	// expose one.
+	async function disk() {
+		const storage = globalThis.navigator?.storage
+		if (!storage?.estimate) return null
+		try {
+			const { usage = 0, quota = 0 } = await storage.estimate()
+			return { free: Math.max(0, quota - usage), total: quota }
+		} catch (error) {
+			return null
+		}
+	}
+
+	// Function: copy
+	// Recursive copy of a file or directory; an existing directory target is
+	// merged into (the operations layer already appends the basename when the
+	// user copies "into" a directory).
+	async function copy(from, to) {
+		const stats = await stat(from)
+		if (!stats) throw notFound(from)
+		if (stats.isDir) {
+			if (!(await stat(to))?.isDir) await ensureDir(to)
+			for await (const handle of (await resolveDir(from)).values()) {
+				await copy(join(from, handle.name), join(to, handle.name))
+			}
+			return
+		}
+		const file = await (await resolveFile(from)).getFile()
+		const directory = await resolveDir(parent(to) ?? "/")
+		const handle = await directory.getFileHandle(basename(to), { create: true })
+		const writable = await handle.createWritable()
+		await writable.write(file)
+		await writable.close()
+	}
+
+	// Function: eraseOne
+	// Removes one entry (recursively for directories); the root is a no-op.
+	async function eraseOne(path) {
+		const normalized = normalize(path)
+		if (normalized === "/") return
+		const directory = await resolveDir(parent(normalized) ?? "/")
+		await directory.removeEntry(basename(normalized), { recursive: true })
+	}
+
+	// Function: trash
+	// Moves entries into `/.trash` under a timestamped name, keeping them
+	// available for inspection instead of deleting them.
+	let trashSeq = 0
+	async function trash(paths) {
+		await ensureDir("/.trash")
+		for (const path of paths) {
+			const normalized = normalize(path)
+			if (normalized === "/") continue
+			const name = `${Date.now()}-${++trashSeq}-${basename(normalized)}`
+			await copy(normalized, join("/.trash", name))
+			await eraseOne(normalized)
+		}
+	}
+
+	// Function: touch
+	// Creates an empty file, or rewrites an existing one to bump its mtime
+	// (OPFS exposes no utimes).
+	async function touch(path) {
+		const normalized = normalize(path)
+		const stats = await stat(normalized)
+		if (stats?.isDir) return
+		const directory = await resolveDir(parent(normalized) ?? "/")
+		const handle = await directory.getFileHandle(basename(normalized), { create: true })
+		if (!stats) return
+		const bytes = await (await handle.getFile()).arrayBuffer()
+		const writable = await handle.createWritable()
+		await writable.write(bytes)
+		await writable.close()
+	}
+
+	// Function: writeText
+	// Creates (or replaces) a UTF-8 text file, creating parent directories.
+	async function writeText(path, text) {
+		const normalized = normalize(path)
+		const directory = await resolveDir(parent(normalized) ?? "/", { create: true })
+		const handle = await directory.getFileHandle(basename(normalized), { create: true })
+		const writable = await handle.createWritable()
+		await writable.write(`${text}`)
+		await writable.close()
+	}
+
+	return {
+		readDir,
+		stat,
+		isDir: async (path) => Boolean((await stat(path))?.isDir),
+		readTextHead,
+		du,
+		disk,
+		copy,
+		move: async (from, to) => {
+			await copy(from, to)
+			await eraseOne(from)
+		},
+		trash,
+		erase: async (paths) => {
+			for (const path of paths) await eraseOne(path)
+		},
+		touch,
+		writeText,
+		home: () => home,
+		cwd: () => home,
+	}
+}
+
+// Function: notFound
+// ENOENT-flavoured error for missing paths.
+function notFound(path) {
+	const error = new Error(`ENOENT: ${path}`)
+	error.code = "ENOENT"
+	return error
+}
+
+export { createOpfsFs }
+
+// EOF

package/src/js/tcmd/web/seed.js

@@ -0,0 +1,90 @@
+// Project: TinyCommand
+// Author:  Sebastien Pierre
+// License: BSD
+// Created: 2026-09-27
+
+// Module: tcmd/web/seed
+// Demo tree for the browser view. `seedOpfs(fs)` writes it once per storage,
+// guarded by a `/.seeded` marker, so a user-emptied tree is not re-populated
+// on every reload. Takes any adapter with `stat` plus the OPFS `writeText`
+// extra (see `web/opfs.js`), which keeps it testable off the browser.
+
+// Constant: DEMO_TREE
+// Absolute path -> UTF-8 contents; parent directories are created on demand.
+const DEMO_TREE = {
+	"/README.md": [
+		"# TinyCommand web",
+		"",
+		"This tree lives in the browser's Origin Private File System (OPFS) and",
+		"is browsed by the very same core that drives the terminal UI.",
+		"",
+		"Handy keys:",
+		"- Enter/Right  open a directory",
+		"- Left/Backspace  go to the parent directory",
+		"- Tab  switch pane",
+		"- Space  mark the current entry",
+		"- b / g  record / jump to a bookmark",
+		"- ^P  command palette",
+		"- :  scripting mode (copy, move, delete, ...)",
+		"- q  quit (unmounts the UI; reload to start over)",
+		"",
+		"Open/edit/run are not available in the browser: the web uses the null",
+		"host adapter, so those commands report `... is not available in this",
+		"environment` in the command bar.",
+		"",
+		"Deleting moves entries to /.trash instead of removing them for good.",
+	].join("\n"),
+	"/home/tester/notes.txt": [
+		"Notes",
+		"=====",
+		"",
+		"- tcmd shares its core between the TUI and the web view",
+		"- components/ holds the renderer-agnostic behaviors",
+		"- tui/ binds them to select.tui, web/ to select.js",
+	].join("\n"),
+	"/home/tester/todo.txt": [
+		"TODO",
+		"----",
+		"[x] two panes",
+		"[x] named bookmarks",
+		"[x] command palette",
+		"[ ] quick find",
+	].join("\n"),
+	"/documents/welcome.txt": [
+		"Welcome to the TinyCommand OPFS demo.",
+		"",
+		"Everything you do here happens in the browser's private storage:",
+		"create tabs, mark files, copy/move/erase inside this tree.",
+		"",
+		"Reload the page and your changes are still there.",
+	].join("\n"),
+	"/documents/tips.txt": [
+		"Tip: the preview follows the cursor; `v` toggles it.",
+		"Tip: `stat` in scripting mode shows size details in the preview.",
+		"Tip: marked entries feed the $A/$B filesets in scripting mode.",
+	].join("\n"),
+	"/projects/tcmd/README.md": [
+		"# tcmd (mirror)",
+		"",
+		"A pretend checkout, good for trying copy/erase on directories.",
+	].join("\n"),
+	"/projects/tcmd/src/main.js": [
+		"export function main() {",
+		'\treturn "hello from a seeded OPFS file"',
+		"}",
+		"",
+	].join("\n"),
+}
+
+// Function: seedOpfs
+// Writes the demo tree when the `/.seeded` marker is absent.
+async function seedOpfs(fs) {
+	if (await fs.stat("/.seeded")) return false
+	for (const [path, text] of Object.entries(DEMO_TREE)) await fs.writeText(path, text)
+	await fs.writeText("/.seeded", "")
+	return true
+}
+
+export { DEMO_TREE, seedOpfs }
+
+// EOF

package/src/js/tcmd/web/server.js

@@ -0,0 +1,191 @@
+// Project: TinyCommand
+// Author:  Sebastien Pierre
+// License: BSD
+// Created: 2026-09-27
+
+// Module: tcmd/web/server
+// Development server for the web view. Serves `public/` and exposes a JSON
+// filesystem API (`/api/*`) over the Node filesystem adapter, so browsers
+// without OPFS (or users who want to browse real files) can run the web UI.
+//
+// Security: binds to loopback only by default and requires the per-process
+// token, injected into `index.html` at serve time, on every API request. When
+// `root` is set, every path is confined to it. This is a local development
+// tool, not a sandbox: it serves the same files `bun run tcmd` can reach, so
+// do not expose the port.
+
+import { resolve as resolvePath, sep } from "node:path"
+import { createNodeFs } from "../core/fs.js"
+
+// Constant: TOKEN_PLACEHOLDER
+// Value replaced in `index.html` when the page is served.
+const TOKEN_PLACEHOLDER = "__TCMD_TOKEN__"
+
+// Function: createWebServer
+// Builds the server. `port` 0 picks a free port (tests); `root` defaults to
+// "/" (the whole filesystem, like the TUI); `token` defaults to a fresh UUID.
+function createWebServer({
+	root = process.env.TCMD_WEB_ROOT ?? "/",
+	port = Number(process.env.PORT ?? 8787),
+	hostname = "127.0.0.1",
+	publicDir = new URL("../../../../public/", import.meta.url),
+	token = crypto.randomUUID(),
+} = {}) {
+	const fs = createNodeFs()
+	const base = resolvePath(root)
+	const rootHref = publicDir instanceof URL ? publicDir : new URL(`${publicDir.replace(/\/?$/, "/")}`, "file:///")
+
+	// Function: withinRoot
+	// True when `path` is the configured root or inside it.
+	function withinRoot(path) {
+		const resolved = resolvePath(path)
+		return base === sep || resolved === base || resolved.startsWith(base + sep)
+	}
+
+	// Function: confine
+	// Resolves a client path and rejects it when it escapes the root.
+	function confine(path) {
+		if (typeof path !== "string" || !path) throw httpError(400, "missing path")
+		const resolved = resolvePath(path)
+		if (!withinRoot(resolved)) throw httpError(403, `path outside ${base}`)
+		return resolved
+	}
+
+	// Function: jsonBody
+	// Reads a JSON request body; other content types are refused so cross-site
+	// form posts cannot reach the mutations.
+	async function jsonBody(request) {
+		if (!`${request.headers.get("content-type") ?? ""}`.includes("application/json")) {
+			throw httpError(415, "expected an application/json body")
+		}
+		try {
+			return await request.json()
+		} catch (error) {
+			throw httpError(400, "malformed JSON body")
+		}
+	}
+
+	// Constant: routes
+	// `METHOD /api/name` -> payload builder; the payload is wrapped in JSON.
+	const routes = {
+		"GET /api/info": () => ({
+			root: base,
+			home: withinRoot(fs.home()) ? fs.home() : base,
+			cwd: withinRoot(fs.cwd()) ? fs.cwd() : base,
+		}),
+		"GET /api/readDir": (_request, url) => fs.readDir(confine(url.searchParams.get("path"))),
+		"GET /api/stat": (_request, url) => fs.stat(confine(url.searchParams.get("path"))),
+		"GET /api/readTextHead": async (_request, url) => {
+			const path = confine(url.searchParams.get("path"))
+			const maxBytes = clampBytes(url.searchParams.get("maxBytes"))
+			return fs.readTextHead(path, maxBytes)
+		},
+		"GET /api/du": (_request, url) => fs.du(confine(url.searchParams.get("path"))),
+		"GET /api/disk": (_request, url) => fs.disk(confine(url.searchParams.get("path"))),
+		"POST /api/copy": async (request) => {
+			const body = await jsonBody(request)
+			return fs.copy(confine(body.from), confine(body.to))
+		},
+		"POST /api/move": async (request) => {
+			const body = await jsonBody(request)
+			return fs.move(confine(body.from), confine(body.to))
+		},
+		"POST /api/trash": async (request) => {
+			const body = await jsonBody(request)
+			return fs.trash(confinePaths(body.paths))
+		},
+		"POST /api/erase": async (request) => {
+			const body = await jsonBody(request)
+			return fs.erase(confinePaths(body.paths))
+		},
+		"POST /api/touch": async (request) => {
+			const body = await jsonBody(request)
+			return fs.touch(confine(body.path))
+		},
+	}
+
+	// Function: confinePaths
+	// Validates a `paths` array before a bulk operation.
+	function confinePaths(paths) {
+		if (!Array.isArray(paths)) throw httpError(400, "expected a paths array")
+		return paths.map(confine)
+	}
+
+	// Function: handleApi
+	// Auth + routing + error mapping for `/api/*`.
+	async function handleApi(request, url) {
+		if (request.headers.get("x-tcmd-token") !== token) {
+			return json({ error: "invalid or missing token" }, 403)
+		}
+		const route = routes[`${request.method} ${url.pathname}`]
+		if (!route) return json({ error: `unknown route: ${request.method} ${url.pathname}` }, 404)
+		try {
+			const value = await route(request, url)
+			return json(value === undefined ? { ok: true } : value)
+		} catch (error) {
+			const status = error?.status ?? (error?.code === "ENOENT" ? 404 : 500)
+			return json({ error: `${error?.message ?? error}` }, status)
+		}
+	}
+
+	// Function: handleStatic
+	// `public/` files, with the token injected into `index.html`.
+	async function handleStatic(url) {
+		let path
+		try {
+			path = decodeURIComponent(url.pathname)
+		} catch (error) {
+			return new Response("Bad request", { status: 400 })
+		}
+		if (path === "/") path = "/index.html"
+		const target = new URL(`.${path}`, rootHref)
+		if (!target.href.startsWith(rootHref.href)) return new Response("Not found", { status: 404 })
+		const file = Bun.file(target)
+		if (!(await file.exists())) return new Response("Not found", { status: 404 })
+		if (path === "/index.html") {
+			const html = (await file.text()).replaceAll(TOKEN_PLACEHOLDER, token)
+			return new Response(html, {
+				headers: { "Cache-Control": "no-store", "Content-Type": "text/html; charset=utf-8" },
+			})
+		}
+		return new Response(file, { headers: { "Cache-Control": "no-store" } })
+	}
+
+	const server = Bun.serve({
+		hostname,
+		port,
+		fetch(request) {
+			const url = new URL(request.url)
+			if (url.pathname.startsWith("/api/")) return handleApi(request, url)
+			return handleStatic(url)
+		},
+	})
+
+	return { server, token, root: base }
+}
+
+// Function: json
+// One-line JSON response.
+function json(payload, status = 200) {
+	return Response.json(payload, { status, headers: { "Cache-Control": "no-store" } })
+}
+
+// Function: httpError
+// Error carrying the HTTP status the API should answer with.
+function httpError(status, message) {
+	const error = new Error(message)
+	error.status = status
+	return error
+}
+
+// Function: clampBytes
+// `maxBytes` query parameter, bounded to 1 MiB; defaults to the preview size.
+function clampBytes(value) {
+	const bytes = Number(value)
+	if (!Number.isFinite(bytes) || bytes <= 0) return 65536
+	return Math.min(Math.floor(bytes), 1024 * 1024)
+}
+
+export { createWebServer, TOKEN_PLACEHOLDER }
+
+// EOF

package/src/js/tcmd/web/theme.js

@@ -0,0 +1,23 @@
+// Project: TinyCommand
+// Author:  Sebastien Pierre
+// License: BSD
+// Created: 2026-09-26
+
+// Module: tcmd/web/theme
+// Web presentation tokens. Colors are expressed as CSS classes, so the web
+// theme only carries the state classes the shared behaviors bind through
+// `out:class`; the TUI colors live in `tui/theme.js`.
+
+const webTheme = {
+	activeClass: "is-active",
+	childClass: "is-child",
+	currentClass: "is-current",
+	dirClass: "is-dir",
+	errorClass: "is-error",
+	rootClass: "is-root",
+	selectedClass: "is-selected",
+}
+
+export { webTheme }
+
+// EOF