@ssebastien/tcmd 0.1.4 → 0.1.7

package/src/js/tcmd/core/operations.js

@@ -10,23 +10,33 @@
 // Operations own their side effects and return a one-line message (shown in
 // the command bar) or undefined.
 //
-// Registry entries carry the presentation metadata the panel renders:
-// `signature`, `description`, `aliases` and an optional `confirmText`. An
-// optional `risk` ("caution" for a move, "destructive" for delete/erase) lets
-// the command panel tint the operation by how dangerous it is.
+// Registry entries carry presentation metadata used by the panel and help:
+// `signature`, `description`, `aliases`, `group` and an optional `confirmText`.
+// An optional `displayCommand(session, argv)` overrides the `[Confirm]` line,
+// and `preview(session, argv, draft)` supplies operation-specific preflight
+// output. `group` places the operation in the command panel (Command, File,
+// Info, Create, Edit, Delete); `sel` is script-only and has none. An optional
+// `risk` ("caution" or "destructive") is the single source for the
+// operation's colour treatment and the panel's two-step `[Confirm]` step.
 //
 // They also carry `args`, the structured signature the command panel renders:
 // one descriptor per positional argument. A descriptor is
-// `{ name, kind, role?, optional?, variadic? }` where `kind` is:
+// `{ name, kind, role?, optional?, variadic?, panelOrder?, prefill? }` where
+// `kind` is:
 // - "selection": one or more paths from a pane's selection (marks, falling
 //   back to the cursor entry). `role` picks the pane: "source" (SRC), "dest"
 //   (DST) or "active" (default).
 // - "dest": a single destination directory (the DST pane's path).
+// - "path": a typeable/browsable path; `prefill: "current"` seeds it with the
+//   active pane's path.
+// - "permissions": the chmod R/W/X grid for u/g/o.
 // - "buffer": a selection-buffer label (`+A`, `-B`, …).
 // - "literal": free text (a name), edited in the panel's text field.
 // - "raw": the rest of the line, unparsed (a shell command).
+// `panelOrder` reorders only the panel rows, leaving the argv order intact.
 
-import { basename, extname, join, normalize, parent as parentOf } from "./path.js"
+import { formatDisk, formatSize } from "./format.js"
+import { basename, extname, join, normalize, parent as parentOf, relative } from "./path.js"
 import { currentPane, currentPaneId, PANE_BUFFERS } from "./pane.js"
 
 // Constant: PATHS_PREFIX
@@ -36,6 +46,27 @@ import { currentPane, currentPaneId, PANE_BUFFERS } from "./pane.js"
 // an async confirm re-runs it.
 const PATHS_PREFIX = "$paths:"
 
+// Function: absolutePath
+// Resolves dot segments in an already absolute path using POSIX path rules.
+function absolutePath(path) {
+	const parts = []
+	for (const part of `${path ?? ""}`.split("/")) {
+		if (!part || part === ".") continue
+		if (part === "..") parts.pop()
+		else parts.push(part)
+	}
+	return `/${parts.join("/")}`
+}
+
+// Function: shellQuote
+// Quotes a token only when needed, so displayed path results and panel previews
+// can be pasted as shell arguments (including spaces or apostrophes).
+function shellQuote(token) {
+	const text = `${token ?? ""}`
+	if (text === "") return "''"
+	return /^[A-Za-z0-9_@%+=:,.\/-]+$/.test(text) ? text : `'${text.replace(/'/g, `'\\''`)}'`
+}
+
 // Function: pathToken
 // Encodes a resolved path list as one `$paths:` token.
 function pathToken(paths) {
@@ -58,8 +89,10 @@ function decodePathToken(text) {
 const operations = [
 	{
 		name: "copy",
+		group: "Edit",
 		signature: "copy FROM TO",
 		description: "Copy files and directories",
+		risk: "caution",
 		arity: { min: 2, max: 2 },
 		args: [
 			{ name: "FROM", kind: "selection", role: "source", variadic: true },
@@ -67,6 +100,7 @@ const operations = [
 		],
 		async run(session, args) {
 			const sources = expandAll(session, [args[0]])
+			assertNoOverlappingPaths(sources, "copy")
 			const targets = expandAll(session, [args[1]])
 			if (targets.length !== 1) throw new Error("copy: TO must be a single path")
 			const [target] = targets
@@ -74,16 +108,139 @@ const operations = [
 				throw new Error("copy: TO must be an existing directory for multiple FROM")
 			}
 			const into = await isDir(session, target)
+			const copies = []
 			for (const source of sources) {
 				if (!(await session.fs.stat(source))) throw new Error(`not found: ${source}`)
-				await session.fs.copy(source, into ? join(target, basename(source)) : target)
+				const destination = into ? join(target, basename(source)) : target
+				const existed = Boolean(await session.fs.stat(destination))
+				await session.fs.copy(source, destination)
+				copies.push({ from: source, to: destination, existed })
 			}
 			await refreshPanes(session)
+			// Undo removes what was copied, but only when nothing pre-existed:
+			// erasing a target that was merged into would drop earlier content.
+			if (copies.every((copy) => !copy.existed)) {
+				let snapshots = await Promise.all(copies.map((copy) => pathSnapshot(session.fs, copy.to)))
+				if (snapshots.some((snapshot) => snapshot === null)) throw new Error("copy target disappeared")
+				recordHistory(session, {
+					label: `copy ${sources.length} path${sources.length === 1 ? "" : "s"} → ${target}`,
+					undo: async () => {
+						for (let i = 0; i < copies.length; i++) {
+							if (JSON.stringify(await pathSnapshot(session.fs, copies[i].to)) !== JSON.stringify(snapshots[i])) {
+								throw new Error(`copy target changed: ${copies[i].to}`)
+							}
+						}
+						await session.fs.erase(copies.map((copy) => copy.to))
+					},
+					redo: async () => {
+						await assertPathsAbsent(session.fs, copies.map((copy) => copy.to))
+						for (const copy of copies) await session.fs.copy(copy.from, copy.to)
+						snapshots = await Promise.all(copies.map((copy) => pathSnapshot(session.fs, copy.to)))
+					},
+				})
+			}
 			return `copied ${sources.length} path${sources.length === 1 ? "" : "s"} to ${target}`
 		},
 	},
+	{
+		name: "mkdir",
+		group: "Create",
+		signature: "mkdir PATH...",
+		description: "Create directories",
+		arity: { min: 1 },
+		args: [
+			{ name: "PATH", kind: "path", mode: "dir", prefill: "current" },
+			{ name: "NAME", kind: "literal" },
+		],
+		async run(session, args, options) {
+			const paths = creationPaths(session, args, options)
+			const requested = new Set()
+			const created = new Set()
+			for (const path of paths) {
+				const normalized = normalize(path)
+				if (requested.has(normalized)) throw new Error(`duplicate path: ${normalized}`)
+				requested.add(normalized)
+				if (await pathExists(session.fs, normalized)) throw new Error(`already exists: ${normalized}`)
+				let current = normalized
+				while (current !== "/") {
+					const stats = await session.fs.stat(current)
+					if (stats) {
+						if (!stats.isDir) throw new Error(`not a directory: ${current}`)
+						break
+					}
+					created.add(current)
+					const parent = parentOf(current)
+					if (!parent || parent === current) break
+					current = parent
+				}
+			}
+			const createdPaths = [...created]
+			try {
+				for (const path of paths) await session.fs.mkdir(path)
+			} catch (error) {
+				await removeCreatedDirs(session.fs, createdPaths)
+				throw error
+			}
+			await refreshPanes(session)
+			recordHistory(session, {
+				label: `mkdir ${paths.map((path) => basename(path)).join(", ")}`,
+				undo: async () => {
+					await removeCreatedDirs(session.fs, createdPaths)
+				},
+				redo: async () => {
+					await assertPathsAbsent(session.fs, createdPaths)
+					for (const path of paths) await session.fs.mkdir(path)
+				},
+			})
+			return `created ${createdPaths.length} director${createdPaths.length === 1 ? "y" : "ies"}`
+		},
+	},
+	{
+		name: "new",
+		group: "Create",
+		signature: "new PATH...",
+		description: "Create empty files",
+		arity: { min: 1 },
+		args: [
+			{ name: "PATH", kind: "path", mode: "dir", prefill: "current" },
+			{ name: "NAME", kind: "literal" },
+		],
+		async run(session, args, options) {
+			const paths = creationPaths(session, args, options)
+			const requested = new Set()
+			for (const path of paths) {
+				const normalized = normalize(path)
+				if (requested.has(normalized)) throw new Error(`duplicate path: ${normalized}`)
+				requested.add(normalized)
+				if (await pathExists(session.fs, normalized)) throw new Error(`already exists: ${normalized}`)
+				const parent = parentOf(normalized)
+				if (parent && !(await session.fs.stat(parent))?.isDir) {
+					throw new Error(`no such directory: ${parent}`)
+				}
+			}
+			for (const path of paths) await session.fs.touch(path)
+			await refreshPanes(session)
+			recordHistory(session, {
+				label: `new ${paths.map((path) => basename(path)).join(", ")}`,
+				undo: async () => {
+					for (const path of paths) {
+						const stats = await session.fs.stat(path)
+						if (!stats) continue
+						if (stats.size > 0) throw new Error(`file changed since new: ${path}`)
+					}
+					await session.fs.erase(paths)
+				},
+				redo: async () => {
+					await assertPathsAbsent(session.fs, paths)
+					for (const path of paths) await session.fs.touch(path)
+				},
+			})
+			return `created ${paths.length} file${paths.length === 1 ? "" : "s"}`
+		},
+	},
 	{
 		name: "move",
+		group: "Edit",
 		signature: "move FROM TO",
 		description: "Move files and directories",
 		risk: "caution",
@@ -94,6 +251,7 @@ const operations = [
 		],
 		async run(session, args) {
 			const sources = expandAll(session, [args[0]])
+			assertNoOverlappingPaths(sources, "move")
 			const targets = expandAll(session, [args[1]])
 			if (targets.length !== 1) throw new Error("move: TO must be a single path")
 			const [target] = targets
@@ -101,18 +259,96 @@ const operations = [
 				throw new Error("move: TO must be an existing directory for multiple FROM")
 			}
 			const into = await isDir(session, target)
-			for (const source of sources) {
-				if (!(await session.fs.stat(source))) throw new Error(`not found: ${source}`)
-				await session.fs.move(source, into ? join(target, basename(source)) : target)
+			const plan = sources.map((source) => ({
+				from: source,
+				to: into ? join(target, basename(source)) : target,
+			}))
+			for (const move of plan) {
+				if (!(await pathExists(session.fs, move.from))) throw new Error(`not found: ${move.from}`)
+			}
+			await assertPathsAbsent(session.fs, plan.map((move) => move.to))
+			const moves = []
+			for (const move of plan) {
+				await session.fs.move(move.from, move.to)
+				moves.push(move)
 			}
 			await refreshPanes(session)
+			recordHistory(session, {
+				label: `move ${sources.length} path${sources.length === 1 ? "" : "s"} → ${target}`,
+				undo: async () => {
+					await moveHistory(session, moves.map(({ from, to }) => ({ from: to, to: from })))
+				},
+				redo: async () => {
+					await moveHistory(session, moves)
+				},
+			})
 			return `moved ${sources.length} path${sources.length === 1 ? "" : "s"} to ${target}`
 		},
 	},
 	{
 		name: "rename",
-		signature: "rename FIND REPLACE PATH...",
-		description: "Rename paths with a literal find-and-replace",
+		group: "Edit",
+		signature: "rename FROM TO PATH",
+		description: "Rename a child path from one name to another",
+		risk: "caution",
+		arity: { min: 3, max: 3 },
+		args: [
+			{ name: "FROM", kind: "literal" },
+			{ name: "TO", kind: "literal" },
+			{ name: "PATH", kind: "path", mode: "dir" },
+		],
+		// The `[Confirm]` line names the two resolved paths relative to the
+		// working directory, rather than the `FROM TO PATH` argument triple the
+		// panel would assemble: `rename docs/a.txt docs/b.txt`.
+		displayCommand(session, argv) {
+			const [fromName, toName, pathToken] = argv
+			if (!fromName || !toName || !pathToken) return null
+			let directory
+			try {
+				directory = expandArg(session, pathToken)[0]
+			} catch {
+				return null
+			}
+			if (!directory) return null
+			const cwd = session.fs.cwd?.() ?? "/"
+			const source = relative(cwd, join(directory, fromName))
+			const target = relative(cwd, join(directory, toName))
+			return `rename ${shellQuote(source)} ${shellQuote(target)}`
+		},
+		async run(session, args) {
+			const fromName = `${args[0] ?? ""}`
+			const toName = `${args[1] ?? ""}`
+			if (!fromName) throw new Error("rename needs FROM")
+			if (!toName) throw new Error("rename needs TO")
+			assertRenameName(fromName, "FROM")
+			assertRenameName(toName, "TO")
+			const paths = expandAll(session, [args[2]])
+			if (paths.length !== 1) throw new Error("rename: PATH must be a single directory")
+			const [directory] = paths
+			if (!(await isDir(session, directory))) throw new Error(`rename: PATH is not a directory: ${directory}`)
+			const move = { from: join(directory, fromName), to: join(directory, toName) }
+			if (move.from === move.to) return "rename: nothing changed"
+			if (!(await pathExists(session.fs, move.from))) throw new Error(`rename: not found: ${move.from}`)
+			await assertPathsAbsent(session.fs, [move.to])
+			await session.fs.move(move.from, move.to)
+			await refreshPanes(session)
+			recordHistory(session, {
+				label: `rename ${fromName} → ${toName}`,
+				undo: async () => {
+					await moveHistory(session, [{ from: move.to, to: move.from }])
+				},
+				redo: async () => {
+					await moveHistory(session, [move])
+				},
+			})
+			return `renamed ${fromName} to ${toName}`
+		},
+	},
+	{
+		name: "replace",
+		group: "Edit",
+		signature: "replace FIND REPLACE PATH...",
+		description: "Replace a literal substring in path names",
 		risk: "caution",
 		arity: { min: 3 },
 		args: [
@@ -133,7 +369,7 @@ const operations = [
 				return null
 			}
 			if (!paths.length) return null
-			const plan = renamePlan(find, replace, paths)
+			const plan = replacePlan(find, replace, paths)
 			const lines = plan.map((row) => {
 				if (row.error) return `${row.name} → ⚠ ${row.error}`
 				if (!row.changed) return `${row.name}  (unchanged)`
@@ -145,33 +381,47 @@ const operations = [
 		async run(session, args) {
 			const find = `${args[0] ?? ""}`
 			const replace = `${args[1] ?? ""}`
-			if (!find) throw new Error("rename needs FIND")
-			if (!replace) throw new Error("rename needs REPLACE")
+			if (!find) throw new Error("replace needs FIND")
+			if (!replace) throw new Error("replace needs REPLACE")
 			const paths = expandAll(session, args.slice(2))
-			if (!paths.length) throw new Error("rename needs at least one path")
-			const plan = renamePlan(find, replace, paths)
+			if (!paths.length) throw new Error("replace needs at least one path")
+			assertNoOverlappingPaths(paths, "replace")
+			const plan = replacePlan(find, replace, paths)
 			const bad = plan.find((row) => row.error)
-			if (bad) throw new Error(`rename ${basename(bad.path)}: ${bad.error}`)
+			if (bad) throw new Error(`replace ${basename(bad.path)}: ${bad.error}`)
 			const duplicates = duplicateTargets(plan)
-			if (duplicates.length) throw new Error(`rename: duplicate target ${duplicates[0]}`)
-			for (const row of plan) {
-				if (!row.changed) continue
-				const target = join(parentOf(row.path), row.newName)
-				if (await session.fs.stat(target)) throw new Error(`rename: ${row.newName} already exists`)
+			if (duplicates.length) throw new Error(`replace: duplicate target ${duplicates[0]}`)
+			const replaceMoves = plan
+				.filter((row) => row.changed)
+				.map((row) => ({ from: row.path, to: join(parentOf(row.path), row.newName) }))
+			for (const move of replaceMoves) {
+				if (!(await pathExists(session.fs, move.from))) throw new Error(`replace: not found: ${move.from}`)
 			}
+			await assertPathsAbsent(session.fs, replaceMoves.map((move) => move.to))
 			let count = 0
-			for (const row of plan) {
-				if (!row.changed) continue
-				await session.fs.move(row.path, join(parentOf(row.path), row.newName))
+			const moves = []
+			for (const move of replaceMoves) {
+				await session.fs.move(move.from, move.to)
+				moves.push(move)
 				count += 1
 			}
 			await refreshPanes(session)
-			if (!count) return "rename: nothing changed"
-			return `renamed ${count} path${count === 1 ? "" : "s"}`
+			if (!count) return "replace: nothing changed"
+			recordHistory(session, {
+				label: `replace ${count} path${count === 1 ? "" : "s"}`,
+				undo: async () => {
+					await moveHistory(session, moves.map(({ from, to }) => ({ from: to, to: from })))
+				},
+				redo: async () => {
+					await moveHistory(session, moves)
+				},
+			})
+			return `replaced ${count} path${count === 1 ? "" : "s"}`
 		},
 	},
 	{
 		name: "delete",
+		group: "Delete",
 		signature: "delete PATH...",
 		description: "Delete paths, moving them to the trash",
 		risk: "destructive",
@@ -179,16 +429,44 @@ const operations = [
 		args: [{ name: "PATH", kind: "selection", role: "active", variadic: true }],
 		async run(session, args) {
 			const paths = expandAll(session, args)
+			assertNoOverlappingPaths(paths, "delete")
 			for (const path of paths) {
 				if (!(await session.fs.stat(path))) throw new Error(`not found: ${path}`)
 			}
-			await session.fs.trash(paths)
+			const trashed = (await session.fs.trash(paths)) ?? []
 			await refreshPanes(session)
-			return `trashed ${paths.length} path${paths.length === 1 ? "" : "s"}`
+			// The trash copies the delete can be undone from. Mutable because a
+			// redo re-trashes under fresh names.
+			let items = trashed.map((entry) => entry?.to ?? entry).filter(Boolean)
+			let restoredSnapshots = null
+			if (items.length) {
+				recordHistory(session, {
+					label: `trash ${paths.length} path${paths.length === 1 ? "" : "s"}`,
+					undo: async () => {
+						await session.fs.restore(items)
+						restoredSnapshots = await Promise.all(paths.map((path) => pathSnapshot(session.fs, path)))
+					},
+					redo: async () => {
+						for (let i = 0; i < paths.length; i++) {
+							if (JSON.stringify(await pathSnapshot(session.fs, paths[i])) !== JSON.stringify(restoredSnapshots?.[i])) {
+								throw new Error(`path changed since restore: ${paths[i]}`)
+							}
+						}
+						const again = (await session.fs.trash(paths)) ?? []
+						items = again.map((entry) => entry?.to ?? entry).filter(Boolean)
+					},
+				})
+			}
+			// Name where the entries went (the trash directory), so the delete is
+			// not a black hole: `u` history or `⇧T` trash bring them back.
+			const where = items.length ? parentOf(items[0]) : null
+			const count = `path${paths.length === 1 ? "" : "s"}`
+			return where ? `trashed ${paths.length} ${count} to ${where}` : `trashed ${paths.length} ${count}`
 		},
 	},
 	{
 		name: "erase",
+		group: "Delete",
 		signature: "erase PATH...",
 		description: "Delete paths without moving them to the trash",
 		risk: "destructive",
@@ -197,13 +475,50 @@ const operations = [
 		confirmText: (args) => `erase ${args.join(" ")} without trash?`,
 		async run(session, args) {
 			const paths = expandAll(session, args)
+			assertNoOverlappingPaths(paths, "erase")
 			await session.fs.erase(paths)
 			await refreshPanes(session)
 			return `erased ${paths.length} path${paths.length === 1 ? "" : "s"}`
 		},
 	},
+	{
+		name: "unlink",
+		group: "Delete",
+		signature: "unlink PATH...",
+		description: "Remove symbolic links, leaving their targets alone",
+		risk: "destructive",
+		arity: { min: 1 },
+		args: [{ name: "PATH", kind: "selection", role: "active", variadic: true }],
+		async run(session, args) {
+			const paths = expandAll(session, args)
+			const links = []
+			for (const path of paths) {
+				const entry = await linkEntry(session.fs, path)
+				// Only links are unlinked: a typo on a regular file must not
+				// remove it. The whole batch is checked before anything runs.
+				if (!entry) throw new Error(`not a symbolic link: ${path}`)
+				links.push({ path, target: entry.target ?? "" })
+			}
+			for (const link of links) await session.fs.unlink(link.path)
+			await refreshPanes(session)
+			if (links.length) {
+				recordHistory(session, {
+					label: `unlink ${links.length} link${links.length === 1 ? "" : "s"}`,
+					undo: async () => {
+						await assertPathsAbsent(session.fs, links.map((link) => link.path))
+						for (const link of links) await session.fs.symlink(link.target, link.path)
+					},
+					redo: async () => {
+						for (const link of links) await session.fs.unlink(link.path)
+					},
+				})
+			}
+			return `unlinked ${links.length} link${links.length === 1 ? "" : "s"}`
+		},
+	},
 	{
 		name: "stat",
+		group: "Info",
 		signature: "stat PATH...",
 		description: "Show file information, including disk usage",
 		arity: { min: 1 },
@@ -211,24 +526,104 @@ const operations = [
 		async run(session, args) {
 			const paths = expandAll(session, args)
 			const details = []
+			const results = []
 			for (const path of paths) {
-				const stats = await session.fs.stat(path)
-				if (!stats) throw new Error(`not found: ${path}`)
-				const size = stats.isDir ? await session.fs.du(path) : stats.size
+				const { stats, size } = await pathUsage(session.fs, path)
+				const summary = `${stats.isDir ? "directory" : "file"} · ${formatSize(size)} · ${new Date(stats.mtimeMs || 0).toISOString()}`
 				details.push(path)
-				details.push(
-					`  ${stats.isDir ? "directory" : "file"} · ${humanSize(size)} · ${new Date(stats.mtimeMs || 0).toISOString()}`,
-				)
+				details.push(`  ${summary}`)
+				results.push(`${path} · ${summary}`)
 			}
-			session.showPreview.set(true)
-			session.previewTarget.set(await previewTarget(session, paths[0], details))
-			return `stat ${paths.join(" ")}`
+			await showDetails(session, paths[0], details)
+			return results.join("; ")
+		},
+	},
+	{
+		name: "du",
+		group: "Info",
+		signature: "du PATH...",
+		aliases: ["usage"],
+		description: "Show disk usage per path (recursive for directories)",
+		arity: { min: 1 },
+		args: [{ name: "PATH", kind: "selection", role: "active", variadic: true }],
+		async run(session, args) {
+			const paths = expandAll(session, args)
+			const details = []
+			let total = 0
+			for (const path of paths) {
+				const { stats, size } = await pathUsage(session.fs, path)
+				total += size
+				details.push(path)
+				details.push(`  ${formatSize(size)}${stats.isDir ? " recursive" : ""}`)
+			}
+			if (paths.length > 1) details.push(`  total: ${formatSize(total)}`)
+			await showDetails(session, paths[0], details)
+			return paths.length === 1
+				? `${formatSize(total)} in ${paths[0]}`
+				: `${formatSize(total)} in ${paths.length} paths`
+		},
+	},
+	{
+		name: "df",
+		group: "Info",
+		signature: "df PATH...",
+		aliases: ["free"],
+		description: "Show filesystem free and total space",
+		arity: { min: 0 },
+		args: [{ name: "PATH", kind: "selection", role: "active", variadic: true }],
+		async run(session, args) {
+			const paths = args.length ? expandAll(session, args) : [currentPane(session).path.value]
+			const details = []
+			const results = []
+			for (const path of paths) {
+				const disk = await session.fs.disk(path)
+				if (!disk) throw new Error(`no filesystem information for ${path}`)
+				const used = Math.max(0, disk.total - disk.free)
+				const percent = disk.total > 0 ? Math.round((used / disk.total) * 100) : 0
+				const summary = `${formatDisk(disk)} (${percent}% used)`
+				details.push(path)
+				details.push(`  ${summary}`)
+				results.push(`${path} · ${summary}`)
+			}
+			await showDetails(session, paths[0], details)
+			return results.join("; ")
+		},
+	},
+	{
+		name: "abspath",
+		group: "File",
+		signature: "abspath PATH...",
+		description: "Show absolute paths",
+		arity: { min: 1 },
+		args: [{ name: "PATH", kind: "selection", role: "active", variadic: true }],
+		async run(session, args) {
+			const text = expandAll(session, args).map((path) => shellQuote(absolutePath(path))).join(" ")
+			copyText(session, text)
+			return text
+		},
+	},
+	{
+		name: "realpath",
+		group: "File",
+		signature: "realpath PATH...",
+		description: "Show resolved paths, following symlinks",
+		arity: { min: 1 },
+		args: [{ name: "PATH", kind: "selection", role: "active", variadic: true }],
+		async run(session, args) {
+			const paths = expandAll(session, args)
+			const resolved = []
+			for (const path of paths) resolved.push(await session.fs.realpath(absolutePath(path)))
+			const text = resolved.map(shellQuote).join(" ")
+			copyText(session, text)
+			return text
 		},
 	},
 	{
 		name: "touch",
+		group: "Edit",
 		signature: "touch PATH...",
 		description: "Create files or bump their modification time",
+		risk: "caution",
 		arity: { min: 1 },
 		args: [{ name: "PATH", kind: "selection", role: "active", variadic: true }],
 		async run(session, args) {
@@ -238,6 +633,53 @@ const operations = [
 			return `touched ${paths.length} path${paths.length === 1 ? "" : "s"}`
 		},
 	},
+	{
+		name: "chmod",
+		group: "Edit",
+		signature: "chmod MODE PATH...",
+		description: "Set read/write/execute permissions for user, group and other",
+		risk: "caution",
+		arity: { min: 2 },
+		args: [
+			{ name: "MODE", kind: "permissions", panelOrder: 1 },
+			{ name: "PATH", kind: "selection", role: "active", variadic: true, panelOrder: 0 },
+		],
+		async run(session, args) {
+			const modeText = `${args[0] ?? ""}`.trim()
+			if (!/^0?[0-7]{1,4}$/.test(modeText)) throw new Error("chmod: MODE must be octal (e.g. 644)")
+			const paths = expandAll(session, args.slice(1))
+			for (const path of paths) {
+				if (!(await session.fs.stat(path))) throw new Error(`not found: ${path}`)
+			}
+			const mode = Number.parseInt(modeText, 8)
+			for (const path of paths) await session.fs.chmod(path, mode)
+			await refreshPanes(session)
+			return `chmod ${modeText} ${paths.length} path${paths.length === 1 ? "" : "s"}`
+		},
+	},
+	{
+		name: "chown",
+		group: "Edit",
+		signature: "chown OWNER PATH...",
+		description: "Set path ownership (OWNER is USER[:GROUP])",
+		risk: "caution",
+		arity: { min: 2 },
+		args: [
+			{ name: "OWNER", kind: "literal", panelOrder: 1 },
+			{ name: "PATH", kind: "selection", role: "active", variadic: true, panelOrder: 0 },
+		],
+		async run(session, args) {
+			const owner = `${args[0] ?? ""}`.trim()
+			if (!owner) throw new Error("chown: OWNER must be USER[:GROUP]")
+			const paths = expandAll(session, args.slice(1))
+			for (const path of paths) {
+				if (!(await session.fs.stat(path))) throw new Error(`not found: ${path}`)
+			}
+			for (const path of paths) await session.fs.chown(path, owner)
+			await refreshPanes(session)
+			return `chowned ${paths.length} path${paths.length === 1 ? "" : "s"} to ${owner}`
+		},
+	},
 	{
 		name: "sel",
 		signature: "sel [+|-][BUF] PATH...",
@@ -266,8 +708,10 @@ const operations = [
 	},
 	{
 		name: "edit",
+		group: "Edit",
 		signature: "edit PATH",
 		description: "Edit a file with $EDITOR",
+		risk: "caution",
 		arity: { min: 1, max: 1 },
 		args: [{ name: "PATH", kind: "selection", role: "active" }],
 		async run(session, args) {
@@ -279,8 +723,52 @@ const operations = [
 			return `edited ${path}`
 		},
 	},
+	{
+		name: "hardlink",
+		group: "Edit",
+		signature: "hardlink FROM TO",
+		description: "Create hard links to paths",
+		risk: "caution",
+		arity: { min: 2, max: 2 },
+		args: [
+			{ name: "FROM", kind: "selection", role: "source", variadic: true },
+			{ name: "TO", kind: "dest" },
+		],
+		async run(session, args) {
+			const links = await linkPlan(session, args, "hardlink")
+			for (const link of links) {
+				const stats = await session.fs.stat(link.from)
+				if (!stats) throw new Error(`not found: ${link.from}`)
+				if (stats.isDir) throw new Error(`hardlink: cannot link a directory: ${link.from}`)
+			}
+			for (const link of links) await session.fs.hardlink(link.from, link.to)
+			await refreshPanes(session)
+			recordLinkHistory(session, "hardlink", links, (link) => session.fs.hardlink(link.from, link.to))
+			return `linked ${links.length} path${links.length === 1 ? "" : "s"} to ${links[0].to}`
+		},
+	},
+	{
+		name: "symlink",
+		group: "Edit",
+		signature: "symlink FROM TO",
+		description: "Create symbolic links to paths",
+		risk: "caution",
+		arity: { min: 2, max: 2 },
+		args: [
+			{ name: "FROM", kind: "selection", role: "source", variadic: true },
+			{ name: "TO", kind: "dest" },
+		],
+		async run(session, args) {
+			const links = await linkPlan(session, args, "symlink")
+			for (const link of links) await session.fs.symlink(link.from, link.to)
+			await refreshPanes(session)
+			recordLinkHistory(session, "symlink", links, (link) => session.fs.symlink(link.from, link.to))
+			return `symlinked ${links.length} path${links.length === 1 ? "" : "s"} to ${links[0].to}`
+		},
+	},
 	{
 		name: "view",
+		group: "File",
 		signature: "view PATH",
 		description: "Preview a path",
 		arity: { min: 1, max: 1 },
@@ -296,6 +784,7 @@ const operations = [
 	},
 	{
 		name: "open",
+		group: "File",
 		signature: "open PATH...",
 		description: "Open paths with the desktop opener",
 		arity: { min: 1 },
@@ -308,6 +797,7 @@ const operations = [
 	},
 	{
 		name: "bookmark",
+		group: "Command",
 		signature: "bookmark [NAME] [PATH]",
 		description: "List, add or remove named bookmarks",
 		arity: { min: 0, max: 2 },
@@ -338,6 +828,7 @@ const operations = [
 	},
 	{
 		name: "run",
+		group: "File",
 		signature: "run CMD",
 		aliases: ["!"],
 		description: "Run a shell command in the active pane",
@@ -433,17 +924,195 @@ function expandAll(session, tokens) {
 	return paths
 }
 
+// Function: creationPaths
+// The paths `new`/`mkdir` create. Scripts keep the one-token-per-path syntax
+// (`new a b`); the command panel supplies a PATH directory plus a NAME and
+// opts into composing them here.
+function creationPaths(session, args, options) {
+	if (!options?.panel) return expandAll(session, args)
+	const directory = `${args[0] ?? ""}`.trim()
+	const names = args.slice(1).map((name) => `${name ?? ""}`.trim()).filter(Boolean)
+	if (!directory || !names.length) return []
+	return expandAll(session, names.map((name) => join(directory, name)))
+}
+
 async function isDir(session, path) {
 	const stats = await session.fs.stat(path)
 	return Boolean(stats?.isDir)
 }
 
+// Function: pathUsage
+// Stats and reported size for an information operation. Directories are
+// measured recursively, so `stat` and `du` share one calculation and one
+// missing-path error.
+async function pathUsage(fs, path) {
+	const stats = await fs.stat(path)
+	if (!stats) throw new Error(`not found: ${path}`)
+	return { stats, size: stats.isDir ? await fs.du(path) : stats.size }
+}
+
 async function refreshPanes(session) {
 	// Every rendered column: the two panes, plus the explorer's parent mirror
 	// and the directory the inspector is showing.
 	await Promise.all(Object.values(session.panes).map((pane) => pane.refresh()))
 }
 
+// Function: copyText
+// Best-effort clipboard write through the host adapter (OSC 52 in the TUI, the
+// Clipboard API in a browser). A host without a clipboard returns false; the
+// operation still reports its result normally.
+function copyText(session, text) {
+	try {
+		return Boolean(session.os?.copy?.(text))
+	} catch (error) {
+		return false
+	}
+}
+
+// Function: linkPlan
+// The source/destination pairs a hardlink or symlink creates: the destination
+// is the TO path, or `TO/basename(source)` when TO is an existing directory —
+// the same rule copy and move use. Every destination must be absent.
+async function linkPlan(session, args, label) {
+	const sources = expandAll(session, [args[0]])
+	const targets = expandAll(session, [args[1]])
+	if (targets.length !== 1) throw new Error(`${label}: TO must be a single path`)
+	const [target] = targets
+	if (sources.length > 1 && !(await isDir(session, target))) {
+		throw new Error(`${label}: TO must be an existing directory for multiple FROM`)
+	}
+	const into = await isDir(session, target)
+	const links = sources.map((source) => ({
+		from: source,
+		to: into ? join(target, basename(source)) : target,
+	}))
+	await assertPathsAbsent(session.fs, links.map((link) => link.to))
+	return links
+}
+
+// Function: recordLinkHistory
+// Journals a batch of links: undo erases them, redo recreates them through the
+// operation that made them (`hardlink` or `symlink`).
+function recordLinkHistory(session, label, links, create) {
+	recordHistory(session, {
+		label: `${label} ${links.length} path${links.length === 1 ? "" : "s"}`,
+		undo: async () => {
+			await session.fs.erase(links.map((link) => link.to))
+		},
+		redo: async () => {
+			await assertPathsAbsent(session.fs, links.map((link) => link.to))
+			for (const link of links) await create(link)
+		},
+	})
+}
+
+// Function: linkEntry
+// The listing entry for `path` when it is a symbolic link (its own identity,
+// not what it points at). Null for a regular file or directory.
+async function linkEntry(fs, path) {
+	const parent = parentOf(path)
+	if (!parent) return null
+	try {
+		const entry = (await fs.readDir(parent)).find((candidate) => candidate.name === basename(path))
+		return entry?.isSymlink ? entry : null
+	} catch (error) {
+		return null
+	}
+}
+
+// Function: recordHistory
+// Journals a reversible operation when the session has a journal (headless
+// hosts and tests may omit it). `entry` is `{ label, undo, redo }`.
+function recordHistory(session, entry) {
+	session.journal?.record?.(entry)
+}
+
+async function pathExists(fs, path) {
+	if (await fs.stat(path)) return true
+	const parent = parentOf(path)
+	if (!parent) return false
+	try {
+		return (await fs.readDir(parent)).some((entry) => entry.name === basename(path))
+	} catch (error) {
+		if (error?.code === "ENOENT" || error?.name === "NotFoundError" || error?.name === "TypeMismatchError") return false
+		throw error
+	}
+}
+
+async function assertPathsAbsent(fs, paths) {
+	const seen = new Set()
+	for (const path of paths) {
+		if (seen.has(path) || (await pathExists(fs, path))) {
+			const error = new Error(`destination already exists: ${path}`)
+			error.code = "EEXIST"
+			throw error
+		}
+		seen.add(path)
+	}
+}
+
+function assertNoOverlappingPaths(paths, label) {
+	for (let i = 0; i < paths.length; i++) {
+		for (let j = i + 1; j < paths.length; j++) {
+			const a = paths[i]
+			const b = paths[j]
+			if (a === b || isAncestorPath(a, b) || isAncestorPath(b, a)) {
+				throw new Error(`${label}: overlapping paths: ${a} and ${b}`)
+			}
+		}
+	}
+}
+
+function isAncestorPath(parent, child) {
+	return child.startsWith(parent === "/" ? "/" : `${parent}/`)
+}
+
+async function moveHistory(session, moves) {
+	await assertPathsAbsent(session.fs, moves.map((move) => move.to))
+	for (const move of moves) await session.fs.move(move.from, move.to)
+}
+
+async function removeCreatedDirs(fs, paths) {
+	const existing = []
+	for (const path of paths) if (await pathExists(fs, path)) existing.push(path)
+	const existingSet = new Set(existing)
+	for (const path of existing) {
+		const expected = new Set(existing.filter((child) => parentOf(child) === path).map(basename))
+		const actual = new Set((await fs.readDir(path)).map((entry) => entry.name))
+		if (actual.size !== expected.size || [...actual].some((name) => !expected.has(name))) {
+			throw new Error(`directory changed since mkdir: ${path}`)
+		}
+	}
+	const deepestFirst = [...existingSet].sort((a, b) => b.split("/").length - a.split("/").length)
+	for (const path of deepestFirst) await fs.erase([path])
+}
+
+async function treeSnapshot(fs, path, entry = null) {
+	const stats = await fs.stat(path)
+	if (!stats) return null
+	const isSymlink = Boolean(entry?.isSymlink || stats.isSymlink)
+	const snapshot = {
+		isDir: Boolean(stats.isDir),
+		isSymlink,
+		size: stats.size ?? 0,
+		mtimeMs: stats.mtimeMs ?? 0,
+		ctimeMs: stats.ctimeMs ?? 0,
+		mode: stats.mode ?? 0,
+		target: isSymlink ? entry?.target ?? null : null,
+	}
+	if (snapshot.isDir && !isSymlink) {
+		const children = (await fs.readDir(path)).sort((a, b) => a.name.localeCompare(b.name))
+		snapshot.children = await Promise.all(children.map((child) => treeSnapshot(fs, child.path, child)))
+	}
+	return snapshot
+}
+
+async function pathSnapshot(fs, path) {
+	const parent = parentOf(path)
+	const entry = parent ? (await fs.readDir(parent)).find((candidate) => candidate.name === basename(path)) : null
+	return treeSnapshot(fs, path, entry)
+}
+
 async function previewTarget(session, path, details) {
 	const stats = await session.fs.stat(path)
 	if (!stats) throw new Error(`not found: ${path}`)
@@ -459,6 +1128,14 @@ async function previewTarget(session, path, details) {
 	return target
 }
 
+// Function: showDetails
+// Opens the preview on `path` with the detail lines an information operation
+// produced, so `stat`, `du` and `df` share the same presentation.
+async function showDetails(session, path, details) {
+	session.showPreview.set(true)
+	session.previewTarget.set(await previewTarget(session, path, details))
+}
+
 // Function: parseSelection
 // Splits `sel` arguments into a sign, an optional buffer label and the path
 // tokens: `+A paths` adds to buffer A (the source pane), `-B paths` removes
@@ -486,12 +1163,12 @@ function findBuffer(session, name) {
 	throw new Error(`unknown selection buffer: ${name}`)
 }
 
-// Function: renamePlan
-// The literal find-and-replace mapping a `rename` runs: one row per path with
+// Function: replacePlan
+// The literal find-and-replace mapping a `replace` runs: one row per path with
 // its source basename, its new basename (every occurrence of FIND replaced by
 // REPLACE), whether it changed, and an error when the result is empty or
 // contains a path separator. Pure, so the panel preview and the run agree.
-function renamePlan(find, replace, paths) {
+function replacePlan(find, replace, paths) {
 	return (paths ?? []).map((path) => {
 		const name = basename(path)
 		const newName = name.split(find).join(replace)
@@ -502,45 +1179,40 @@ function renamePlan(find, replace, paths) {
 	})
 }
 
+function assertRenameName(name, argument) {
+	if (name === "." || name === ".." || name.includes("/") || name.includes("\0")) {
+		throw new Error(`rename: ${argument} must be a single name`)
+	}
+}
+
 // Function: duplicateTargets
-// The new names two or more different paths would collide on.
+// The destination paths two or more changed paths would collide on. Basenames
+// may repeat safely when their files live in different directories.
 function duplicateTargets(plan) {
 	const seen = new Set()
 	const duplicates = new Set()
 	for (const row of plan ?? []) {
 		if (!row.changed) continue
-		if (seen.has(row.newName)) duplicates.add(row.newName)
-		seen.add(row.newName)
+		const target = join(parentOf(row.path), row.newName)
+		if (seen.has(target)) duplicates.add(target)
+		seen.add(target)
 	}
 	return [...duplicates]
 }
 
-// Function: humanSize
-// Compact byte size for stat output (core-local: components own presentation
-// formatting).
-function humanSize(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]}`
-}
-
 export {
+	absolutePath,
 	expandAll,
 	expandArg,
 	decodePathToken,
 	getOperation,
 	getOperations,
-	humanSize,
 	pathToken,
-	renamePlan,
+	recordHistory,
+	refreshPanes,
+	replacePlan,
 	runOperation,
+	shellQuote,
 }
 
 // EOF